aubio  0.4.1
temporal/filter.h
Go to the documentation of this file.
00001 /*
00002   Copyright (C) 2003-2013 Paul Brossier <piem@aubio.org>
00003 
00004   This file is part of aubio.
00005 
00006   aubio is free software: you can redistribute it and/or modify
00007   it under the terms of the GNU General Public License as published by
00008   the Free Software Foundation, either version 3 of the License, or
00009   (at your option) any later version.
00010 
00011   aubio is distributed in the hope that it will be useful,
00012   but WITHOUT ANY WARRANTY; without even the implied warranty of
00013   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014   GNU General Public License for more details.
00015 
00016   You should have received a copy of the GNU General Public License
00017   along with aubio.  If not, see <http://www.gnu.org/licenses/>.
00018 
00019 */
00020 
00021 #ifndef _AUBIO_FILTER_H
00022 #define _AUBIO_FILTER_H
00023 
00024 /** \file 
00025 
00026   Digital filter
00027 
00028   This object stores a digital filter of order \f$n\f$.
00029   It contains the following data:
00030     - \f$ n*1 b_i \f$ feedforward coefficients 
00031     - \f$ n*1 a_i \f$ feedback coefficients 
00032     - \f$ n*c x_i \f$ input signal
00033     - \f$ n*c y_i \f$ output signal
00034 
00035   For convenience, the samplerate of the input signal is also stored in the
00036   object.
00037 
00038   Feedforward and feedback parameters can be modified using
00039   aubio_filter_get_feedback() and aubio_filter_get_feedforward().
00040 
00041   The function aubio_filter_do_outplace() computes the following output signal
00042   \f$ y[n] \f$ from the input signal \f$ x[n] \f$:
00043  
00044   \f{eqnarray*}{
00045      y[n] = b_0 x[n] & + & b_1 x[n-1] + b_2 x[n-2] + ... + b_P x[n-P] \\
00046                      & - & a_1 y[n-1] - a_2 y[n-2] - ... - a_P y[n-P] \\
00047   \f}
00048 
00049   The function aubio_filter_do() executes the same computation but modifies
00050   directly the input signal (in-place).
00051 
00052   The function aubio_filter_do_filtfilt() version runs the filter twice, first
00053   forward then backward, to compensate with the phase shifting of the forward
00054   operation.
00055 
00056   Some convenience functions are provided: 
00057     - new_aubio_filter_a_weighting() and aubio_filter_set_a_weighting(),
00058     - new_aubio_filter_c_weighting() and aubio_filter_set_c_weighting().
00059     - new_aubio_filter_biquad() and aubio_filter_set_biquad().
00060 
00061   \example temporal/test-filter.c
00062  
00063 */
00064 
00065 #ifdef __cplusplus
00066 extern "C" {
00067 #endif
00068 
00069 /** Digital filter
00070 
00071 */
00072 typedef struct _aubio_filter_t aubio_filter_t;
00073 
00074 /** filter input vector (in-place)
00075 
00076   \param f filter object as returned by new_aubio_filter()
00077   \param in input vector to filter
00078 
00079 */
00080 void aubio_filter_do (aubio_filter_t * f, fvec_t * in);
00081 
00082 /** filter input vector (out-of-place)
00083 
00084   \param f filter object as returned by new_aubio_filter()
00085   \param in input vector to filter
00086   \param out output vector to store filtered input
00087 
00088 */
00089 void aubio_filter_do_outplace (aubio_filter_t * f, fvec_t * in, fvec_t * out);
00090 
00091 /** filter input vector forward and backward
00092 
00093   \param f ::aubio_filter_t object as returned by new_aubio_filter()
00094   \param in ::fvec_t input vector to filter
00095   \param tmp memory space to use for computation
00096 
00097 */
00098 void aubio_filter_do_filtfilt (aubio_filter_t * f, fvec_t * in, fvec_t * tmp);
00099 
00100 /** returns a pointer to feedback coefficients \f$ a_i \f$
00101 
00102   \param f filter object to get parameters from
00103 
00104   \return a pointer to the \f$ a_0 ... a_i ... a_P \f$ coefficients
00105 
00106 */
00107 lvec_t *aubio_filter_get_feedback (aubio_filter_t * f);
00108 
00109 /** returns a pointer to feedforward coefficients \f$ b_i \f$
00110 
00111   \param f filter object to get coefficients from
00112 
00113   \return a pointer to the \f$ b_0 ... b_i ... b_P \f$ coefficients
00114 
00115 */
00116 lvec_t *aubio_filter_get_feedforward (aubio_filter_t * f);
00117 
00118 /** get order of the filter
00119 
00120   \param f filter to get order from
00121 
00122   \return the order of the filter
00123 
00124 */
00125 uint_t aubio_filter_get_order (aubio_filter_t * f);
00126 
00127 /** get sampling rate of the filter
00128 
00129   \param f filter to get sampling rate from
00130 
00131   \return the sampling rate of the filter, in Hz
00132 
00133 */
00134 uint_t aubio_filter_get_samplerate (aubio_filter_t * f);
00135 
00136 /** get sampling rate of the filter
00137 
00138   \param f filter to get sampling rate from
00139   \param samplerate sample rate to set the filter to
00140 
00141   \return the sampling rate of the filter, in Hz
00142 
00143 */
00144 uint_t aubio_filter_set_samplerate (aubio_filter_t * f, uint_t samplerate);
00145 
00146 /** reset filter memory
00147 
00148   \param f filter object as returned by new_aubio_filter()
00149 
00150 */
00151 void aubio_filter_do_reset (aubio_filter_t * f);
00152 
00153 /** create new filter object
00154 
00155   This function creates a new ::aubio_filter_t object, given the order of the
00156   filter.
00157 
00158   \param order order of the filter (number of coefficients)
00159 
00160   \return the newly created filter object
00161 
00162 */
00163 aubio_filter_t *new_aubio_filter (uint_t order);
00164 
00165 /** delete a filter object
00166  
00167   \param f filter object to delete
00168 
00169 */
00170 void del_aubio_filter (aubio_filter_t * f);
00171 
00172 #ifdef __cplusplus
00173 }
00174 #endif
00175 
00176 #endif /* _AUBIO_FILTER_H */
 All Data Structures Files Functions Variables Typedefs Defines