aubio  0.4.9
filter.h
Go to the documentation of this file.
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 #ifndef AUBIO_FILTER_H
22 #define AUBIO_FILTER_H
23 
24 /** \file
25 
26  Digital filter
27 
28  This object stores a digital filter of order \f$n\f$.
29  It contains the following data:
30  - \f$ n*1 b_i \f$ feedforward coefficients
31  - \f$ n*1 a_i \f$ feedback coefficients
32  - \f$ n*c x_i \f$ input signal
33  - \f$ n*c y_i \f$ output signal
34 
35  For convenience, the samplerate of the input signal is also stored in the
36  object.
37 
38  Feedforward and feedback parameters can be modified using
39  aubio_filter_get_feedback() and aubio_filter_get_feedforward().
40 
41  The function aubio_filter_do_outplace() computes the following output signal
42  \f$ y[n] \f$ from the input signal \f$ x[n] \f$:
43 
44  \f{eqnarray*}{
45  y[n] = b_0 x[n] & + & b_1 x[n-1] + b_2 x[n-2] + ... + b_P x[n-P] \\
46  & - & a_1 y[n-1] - a_2 y[n-2] - ... - a_P y[n-P] \\
47  \f}
48 
49  The function aubio_filter_do() executes the same computation but modifies
50  directly the input signal (in-place).
51 
52  The function aubio_filter_do_filtfilt() version runs the filter twice, first
53  forward then backward, to compensate with the phase shifting of the forward
54  operation.
55 
56  Some convenience functions are provided:
57  - new_aubio_filter_a_weighting() and aubio_filter_set_a_weighting(),
58  - new_aubio_filter_c_weighting() and aubio_filter_set_c_weighting().
59  - new_aubio_filter_biquad() and aubio_filter_set_biquad().
60 
61  \example temporal/test-filter.c
62 
63 */
64 
65 #ifdef __cplusplus
66 extern "C" {
67 #endif
68 
69 /** Digital filter
70 
71 */
72 typedef struct _aubio_filter_t aubio_filter_t;
73 
74 /** filter input vector (in-place)
75 
76  \param f filter object as returned by new_aubio_filter()
77  \param in input vector to filter
78 
79 */
80 void aubio_filter_do (aubio_filter_t * f, fvec_t * in);
81 
82 /** filter input vector (out-of-place)
83 
84  \param f filter object as returned by new_aubio_filter()
85  \param in input vector to filter
86  \param out output vector to store filtered input
87 
88 */
89 void aubio_filter_do_outplace (aubio_filter_t * f, const fvec_t * in, fvec_t * out);
90 
91 /** filter input vector forward and backward
92 
93  \param f ::aubio_filter_t object as returned by new_aubio_filter()
94  \param in ::fvec_t input vector to filter
95  \param tmp memory space to use for computation
96 
97 */
99 
100 /** returns a pointer to feedback coefficients \f$ a_i \f$
101 
102  \param f filter object to get parameters from
103 
104  \return a pointer to the \f$ a_0 ... a_i ... a_P \f$ coefficients
105 
106 */
108 
109 /** returns a pointer to feedforward coefficients \f$ b_i \f$
110 
111  \param f filter object to get coefficients from
112 
113  \return a pointer to the \f$ b_0 ... b_i ... b_P \f$ coefficients
114 
115 */
117 
118 /** get order of the filter
119 
120  \param f filter to get order from
121 
122  \return the order of the filter
123 
124 */
126 
127 /** get sampling rate of the filter
128 
129  \param f filter to get sampling rate from
130 
131  \return the sampling rate of the filter, in Hz
132 
133 */
135 
136 /** get sampling rate of the filter
137 
138  \param f filter to get sampling rate from
139  \param samplerate sample rate to set the filter to
140 
141  \return the sampling rate of the filter, in Hz
142 
143 */
145 
146 /** reset filter memory
147 
148  \param f filter object as returned by new_aubio_filter()
149 
150 */
152 
153 /** create new filter object
154 
155  This function creates a new ::aubio_filter_t object, given the order of the
156  filter.
157 
158  \param order order of the filter (number of coefficients)
159 
160  \return the newly created filter object
161 
162 */
164 
165 /** delete a filter object
166 
167  \param f filter object to delete
168 
169 */
171 
172 #ifdef __cplusplus
173 }
174 #endif
175 
176 #endif /* AUBIO_FILTER_H */
void aubio_filter_do_outplace(aubio_filter_t *f, const fvec_t *in, fvec_t *out)
filter input vector (out-of-place)
lvec_t * aubio_filter_get_feedforward(const aubio_filter_t *f)
returns a pointer to feedforward coefficients
lvec_t * aubio_filter_get_feedback(const aubio_filter_t *f)
returns a pointer to feedback coefficients
uint_t aubio_filter_get_samplerate(const aubio_filter_t *f)
get sampling rate of the filter
uint_t aubio_filter_set_samplerate(aubio_filter_t *f, uint_t samplerate)
get sampling rate of the filter
void del_aubio_filter(aubio_filter_t *f)
delete a filter object
void aubio_filter_do(aubio_filter_t *f, fvec_t *in)
filter input vector (in-place)
void aubio_filter_do_reset(aubio_filter_t *f)
reset filter memory
Buffer for real data.
Definition: fvec.h:67
uint_t aubio_filter_get_order(const aubio_filter_t *f)
get order of the filter
unsigned int uint_t
unsigned integer
Definition: types.h:60
aubio_filter_t * new_aubio_filter(uint_t order)
create new filter object
struct _aubio_filter_t aubio_filter_t
Digital filter.
Definition: filter.h:72
void aubio_filter_do_filtfilt(aubio_filter_t *f, fvec_t *in, fvec_t *tmp)
filter input vector forward and backward
Buffer for real data in double precision.
Definition: lvec.h:43