GNU Radio 3.7.1 C++ API
firdes.h
Go to the documentation of this file.
00001 /* -*- c++ -*- */
00002 /*
00003  * Copyright 2002,2008,2012 Free Software Foundation, Inc.
00004  *
00005  * This file is part of GNU Radio
00006  *
00007  * GNU Radio is free software; you can redistribute it and/or modify
00008  * it under the terms of the GNU General Public License as published by
00009  * the Free Software Foundation; either version 3, or (at your option)
00010  * any later version.
00011  *
00012  * GNU Radio is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU General Public License for more details.
00016  *
00017  * You should have received a copy of the GNU General Public License
00018  * along with GNU Radio; see the file COPYING.  If not, write to
00019  * the Free Software Foundation, Inc., 51 Franklin Street,
00020  * Boston, MA 02110-1301, USA.
00021  */
00022 
00023 #ifndef _FILTER_FIRDES_H_
00024 #define _FILTER_FIRDES_H_
00025 
00026 #include <gnuradio/filter/api.h>
00027 #include <vector>
00028 #include <cmath>
00029 #include <gnuradio/gr_complex.h>
00030 
00031 namespace gr {
00032   namespace filter {
00033 
00034     /*!
00035      * \brief Finite Impulse Response (FIR) filter design functions.
00036      * \ingroup filter_design
00037      */
00038     
00039     class FILTER_API firdes {
00040     public:
00041             
00042       enum win_type {
00043         WIN_NONE = -1,   // don't use a window
00044         WIN_HAMMING = 0,        // max attenuation 53 dB
00045         WIN_HANN = 1,   // max attenuation 44 dB
00046         WIN_BLACKMAN = 2,       // max attenuation 74 dB
00047         WIN_RECTANGULAR = 3,
00048         WIN_KAISER = 4,     // max attenuation a function of beta, google it
00049         WIN_BLACKMAN_hARRIS = 5,
00050         WIN_BLACKMAN_HARRIS = 5, // alias for capitalization consistency
00051       };
00052 
00053 
00054       // ... class methods ...
00055       
00056       /*!
00057        * \brief use "window method" to design a low-pass FIR filter
00058        *
00059        * \p gain:               overall gain of filter (typically 1.0)
00060        * \p sampling_freq:      sampling freq (Hz)
00061        * \p cutoff_freq:        center of transition band (Hz)
00062        * \p transition_width:   width of transition band (Hz).
00063        *                        The normalized width of the transition
00064        *                        band is what sets the number of taps
00065        *                        required.  Narrow --> more taps
00066        * \p window_type:        What kind of window to use. Determines
00067        *                        maximum attenuation and passband ripple.
00068        * \p beta:               parameter for Kaiser window
00069        */
00070       static std::vector<float>
00071         low_pass(double gain,
00072                  double sampling_freq,
00073                  double cutoff_freq,            // Hz center of transition band
00074                  double transition_width,       // Hz width of transition band
00075                  win_type window = WIN_HAMMING,
00076                  double beta = 6.76);           // used only with Kaiser
00077       
00078       /*!
00079        * \brief use "window method" to design a low-pass FIR filter
00080        *
00081        * \p gain:               overall gain of filter (typically 1.0)
00082        * \p sampling_freq:      sampling freq (Hz)
00083        * \p cutoff_freq:        center of transition band (Hz)
00084        * \p transition_width:   width of transition band (Hz).
00085        * \p attenuation_dB      required stopband attenuation
00086        *                        The normalized width of the transition
00087        *                        band and the required stop band
00088        *                        attenuation is what sets the number of taps
00089        *                        required.  Narrow --> more taps
00090        *                        More attenuatin --> more taps
00091        * \p window_type:        What kind of window to use. Determines
00092        *                        maximum attenuation and passband ripple.
00093        * \p beta:               parameter for Kaiser window
00094        */
00095 
00096       static std::vector<float>
00097         low_pass_2(double gain,
00098                    double sampling_freq,
00099                    double cutoff_freq,          // Hz beginning transition band
00100                    double transition_width,     // Hz width of transition band
00101                    double attenuation_dB,       // out of band attenuation dB
00102                    win_type window = WIN_HAMMING,
00103                    double beta = 6.76);         // used only with Kaiser
00104 
00105       /*!
00106        * \brief use "window method" to design a high-pass FIR filter
00107        *
00108        * \p gain:               overall gain of filter (typically 1.0)
00109        * \p sampling_freq:      sampling freq (Hz)
00110        * \p cutoff_freq:        center of transition band (Hz)
00111        * \p transition_width:   width of transition band (Hz).
00112        *                        The normalized width of the transition
00113        *                        band is what sets the number of taps
00114        *                        required.  Narrow --> more taps
00115        * \p window_type:        What kind of window to use. Determines
00116        *                        maximum attenuation and passband ripple.
00117        * \p beta:               parameter for Kaiser window
00118        */
00119       
00120       static std::vector<float>
00121         high_pass(double gain,
00122                   double sampling_freq,
00123                   double cutoff_freq,           // Hz center of transition band
00124                   double transition_width,      // Hz width of transition band
00125                   win_type window = WIN_HAMMING,
00126                   double beta = 6.76);          // used only with Kaiser
00127 
00128       /*!
00129        * \brief use "window method" to design a high-pass FIR filter
00130        *
00131        * \p gain:               overall gain of filter (typically 1.0)
00132        * \p sampling_freq:      sampling freq (Hz)
00133        * \p cutoff_freq:        center of transition band (Hz)
00134        * \p transition_width:   width of transition band (Hz).
00135        * \p attenuation_dB      out of band attenuation
00136        *                        The normalized width of the transition
00137        *                        band and the required stop band
00138        *                        attenuation is what sets the number of taps
00139        *                        required.  Narrow --> more taps
00140        *                        More attenuation --> more taps
00141        * \p window_type:        What kind of window to use. Determines
00142        *                        maximum attenuation and passband ripple.
00143        * \p beta:               parameter for Kaiser window
00144        */
00145       
00146       static std::vector<float>
00147         high_pass_2(double gain,
00148                     double sampling_freq,
00149                     double cutoff_freq,         // Hz center of transition band
00150                     double transition_width,    // Hz width of transition band
00151                     double attenuation_dB,      // out of band attenuation dB
00152                     win_type window = WIN_HAMMING,
00153                     double beta = 6.76);        // used only with Kaiser
00154       
00155       /*!
00156        * \brief use "window method" to design a band-pass FIR filter
00157        *
00158        * \p gain:               overall gain of filter (typically 1.0)
00159        * \p sampling_freq:      sampling freq (Hz)
00160        * \p low_cutoff_freq:    center of transition band (Hz)
00161        * \p high_cutoff_freq:   center of transition band (Hz)
00162        * \p transition_width:   width of transition band (Hz).
00163        *                        The normalized width of the transition
00164        *                        band is what sets the number of taps
00165        *                        required.  Narrow --> more taps
00166        * \p window_type:        What kind of window to use. Determines
00167        *                        maximum attenuation and passband ripple.
00168        * \p beta:               parameter for Kaiser window
00169        */
00170       static std::vector<float>
00171         band_pass(double gain,
00172                   double sampling_freq,
00173                   double low_cutoff_freq,       // Hz center of transition band
00174                   double high_cutoff_freq,      // Hz center of transition band
00175                   double transition_width,      // Hz width of transition band
00176                   win_type window = WIN_HAMMING,
00177                   double beta = 6.76);          // used only with Kaiser
00178       
00179       /*!
00180        * \brief use "window method" to design a band-pass FIR filter
00181        *
00182        * \p gain:               overall gain of filter (typically 1.0)
00183        * \p sampling_freq:      sampling freq (Hz)
00184        * \p low_cutoff_freq:    center of transition band (Hz)
00185        * \p high_cutoff_freq:   center of transition band (Hz)
00186        * \p transition_width:   width of transition band (Hz).
00187        * \p attenuation_dB      out of band attenuation
00188        *                        The normalized width of the transition
00189        *                        band and the required stop band
00190        *                        attenuation is what sets the number of taps
00191        *                        required.  Narrow --> more taps
00192        *                        More attenuation --> more taps
00193        * \p window_type:        What kind of window to use. Determines
00194        *                        maximum attenuation and passband ripple.
00195        * \p beta:               parameter for Kaiser window
00196        */
00197       
00198       static std::vector<float>
00199         band_pass_2(double gain,
00200                     double sampling_freq,
00201                     double low_cutoff_freq,     // Hz beginning transition band
00202                     double high_cutoff_freq,    // Hz beginning transition band
00203                     double transition_width,    // Hz width of transition band
00204                     double attenuation_dB,      // out of band attenuation dB
00205                     win_type window = WIN_HAMMING,
00206                     double beta = 6.76);        // used only with Kaiser
00207       
00208       /*!
00209        * \brief use "window method" to design a complex band-pass FIR filter
00210        *
00211        * \p gain:               overall gain of filter (typically 1.0)
00212        * \p sampling_freq:      sampling freq (Hz)
00213        * \p low_cutoff_freq:    center of transition band (Hz)
00214        * \p high_cutoff_freq:   center of transition band (Hz)
00215        * \p transition_width:   width of transition band (Hz).
00216        *                        The normalized width of the transition
00217        *                        band is what sets the number of taps
00218        *                        required.  Narrow --> more taps
00219        * \p window_type:        What kind of window to use. Determines
00220        *                        maximum attenuation and passband ripple.
00221        * \p beta:               parameter for Kaiser window
00222        */
00223       static std::vector<gr_complex>
00224         complex_band_pass(double gain,
00225                           double sampling_freq,
00226                           double low_cutoff_freq,       // Hz center of transition band
00227                           double high_cutoff_freq,      // Hz center of transition band
00228                           double transition_width,      // Hz width of transition band
00229                           win_type window = WIN_HAMMING,
00230                           double beta = 6.76);          // used only with Kaiser
00231       
00232       /*!
00233        * \brief use "window method" to design a complex band-pass FIR filter
00234        *
00235        * \p gain:               overall gain of filter (typically 1.0)
00236        * \p sampling_freq:      sampling freq (Hz)
00237        * \p low_cutoff_freq:    center of transition band (Hz)
00238        * \p high_cutoff_freq:   center of transition band (Hz)
00239        * \p transition_width:   width of transition band (Hz).
00240        * \p attenuation_dB      out of band attenuation
00241        *                        The normalized width of the transition
00242        *                        band and the required stop band
00243        *                        attenuation is what sets the number of taps
00244        *                        required.  Narrow --> more taps
00245        *                        More attenuation --> more taps
00246        * \p window_type:        What kind of window to use. Determines
00247        *                        maximum attenuation and passband ripple.
00248        * \p beta:               parameter for Kaiser window
00249        */
00250       
00251       static std::vector<gr_complex>
00252         complex_band_pass_2(double gain,
00253                             double sampling_freq,
00254                             double low_cutoff_freq,     // Hz beginning transition band
00255                             double high_cutoff_freq,    // Hz beginning transition band
00256                             double transition_width,    // Hz width of transition band
00257                             double attenuation_dB,      // out of band attenuation dB
00258                             win_type window = WIN_HAMMING,
00259                             double beta = 6.76);        // used only with Kaiser
00260       
00261       /*!
00262        * \brief use "window method" to design a band-reject FIR filter
00263        *
00264        * \p gain:               overall gain of filter (typically 1.0)
00265        * \p sampling_freq:      sampling freq (Hz)
00266        * \p low_cutoff_freq:    center of transition band (Hz)
00267        * \p high_cutoff_freq:   center of transition band (Hz)
00268        * \p transition_width:   width of transition band (Hz).
00269        *                        The normalized width of the transition
00270        *                        band is what sets the number of taps
00271        *                        required.  Narrow --> more taps
00272        * \p window_type:        What kind of window to use. Determines
00273        *                        maximum attenuation and passband ripple.
00274        * \p beta:               parameter for Kaiser window
00275        */
00276       
00277       static std::vector<float>
00278         band_reject(double gain,
00279                     double sampling_freq,
00280                     double low_cutoff_freq,     // Hz center of transition band
00281                     double high_cutoff_freq,    // Hz center of transition band
00282                     double transition_width,    // Hz width of transition band
00283                     win_type window = WIN_HAMMING,
00284                     double beta = 6.76);        // used only with Kaiser
00285       
00286       /*!
00287        * \brief use "window method" to design a band-reject FIR filter
00288        *
00289        * \p gain:               overall gain of filter (typically 1.0)
00290        * \p sampling_freq:      sampling freq (Hz)
00291        * \p low_cutoff_freq:    center of transition band (Hz)
00292        * \p high_cutoff_freq:   center of transition band (Hz)
00293        * \p transition_width:   width of transition band (Hz).
00294        * \p attenuation_dB      out of band attenuation
00295        *                        The normalized width of the transition
00296        *                        band and the required stop band
00297        *                        attenuation is what sets the number of taps
00298        *                        required.  Narrow --> more taps
00299        *                        More attenuation --> more taps
00300        * \p window_type:        What kind of window to use. Determines
00301        *                        maximum attenuation and passband ripple.
00302        * \p beta:               parameter for Kaiser window
00303        */
00304       
00305       static std::vector<float>
00306         band_reject_2(double gain,
00307                       double sampling_freq,
00308                       double low_cutoff_freq,   // Hz beginning transition band
00309                       double high_cutoff_freq,  // Hz beginning transition band
00310                       double transition_width,  // Hz width of transition band
00311                       double attenuation_dB,    // out of band attenuation dB
00312                       win_type window = WIN_HAMMING,
00313                       double beta = 6.76);      // used only with Kaiser
00314       
00315       /*!\brief design a Hilbert Transform Filter
00316        *
00317        * \p ntaps:              Number of taps, must be odd
00318        * \p window_type:        What kind of window to use
00319        * \p beta:               Only used for Kaiser
00320        */
00321       static std::vector<float>
00322         hilbert(unsigned int ntaps = 19,
00323                 win_type windowtype = WIN_RECTANGULAR,
00324                 double beta = 6.76);
00325       
00326       /*!
00327        * \brief design a Root Cosine FIR Filter (do we need a window?)
00328        *
00329        * \p gain:               overall gain of filter (typically 1.0)
00330        * \p sampling_freq:      sampling freq (Hz)
00331        * \p symbol rate:        symbol rate, must be a factor of sample rate
00332        * \p alpha:              excess bandwidth factor
00333        * \p ntaps:              number of taps
00334        */
00335       static std::vector<float>
00336         root_raised_cosine(double gain,
00337                            double sampling_freq,
00338                            double symbol_rate, // Symbol rate, NOT bitrate (unless BPSK)
00339                            double alpha,       // Excess Bandwidth Factor
00340                            int ntaps);
00341       
00342       /*!
00343        * \brief design a Gaussian filter
00344        *
00345        * \p gain:               overall gain of filter (typically 1.0)
00346        * \p symbols per bit:    symbol rate, must be a factor of sample rate
00347        * \p ntaps:              number of taps
00348        */
00349       static std::vector<float>
00350         gaussian(double gain,
00351                  double spb,
00352                  double bt,     // Bandwidth to bitrate ratio
00353                  int ntaps);
00354       
00355       // window functions ...
00356       static std::vector<float> window (win_type type, int ntaps, double beta);
00357       
00358     private:
00359       static double bessi0(double x);
00360       static void sanity_check_1f(double sampling_freq, double f1,
00361                                   double transition_width);
00362       static void sanity_check_2f(double sampling_freq, double f1, double f2,
00363                                   double transition_width);
00364       static void sanity_check_2f_c(double sampling_freq, double f1, double f2,
00365                                     double transition_width);
00366       
00367       static int compute_ntaps(double sampling_freq,
00368                                double transition_width,
00369                                win_type window_type, double beta);
00370       
00371       static int compute_ntaps_windes(double sampling_freq,
00372                                       double transition_width,
00373                                       double attenuation_dB);
00374     };
00375     
00376   } /* namespace filter */
00377 } /* namespace gr */
00378 
00379 #endif /* _FILTER_FIRDES_H_ */