GNU Radio 3.5.1 C++ API
gr_pfb_arb_resampler_ccf.h
Go to the documentation of this file.
00001 /* -*- c++ -*- */
00002 /*
00003  * Copyright 2009,2010 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 
00024 #ifndef INCLUDED_GR_PFB_ARB_RESAMPLER_CCF_H
00025 #define INCLUDED_GR_PFB_ARB_RESAMPLER_CCF_H
00026 
00027 #include <gr_core_api.h>
00028 #include <gr_block.h>
00029 
00030 class gr_pfb_arb_resampler_ccf;
00031 typedef boost::shared_ptr<gr_pfb_arb_resampler_ccf> gr_pfb_arb_resampler_ccf_sptr;
00032 GR_CORE_API gr_pfb_arb_resampler_ccf_sptr gr_make_pfb_arb_resampler_ccf (float rate,
00033                                                              const std::vector<float> &taps,
00034                                                              unsigned int filter_size=32);
00035 
00036 class gr_fir_ccf;
00037 
00038 /*!
00039  * \class gr_pfb_arb_resampler_ccf
00040  *
00041  * \brief Polyphase filterbank arbitrary resampler with 
00042  *        gr_complex input, gr_complex output and float taps
00043  *
00044  * \ingroup filter_blk
00045  * \ingroup pfb_blk
00046  * 
00047  * This block takes in a signal stream and performs arbitrary
00048  * resampling. The resampling rate can be any real
00049  * number <EM>r</EM>. The resampling is done by constructing
00050  * <EM>N</EM> filters where <EM>N</EM> is the interpolation rate.  We
00051  * then calculate <EM>D</EM> where <EM>D = floor(N/r)</EM>.
00052  *
00053  * Using <EM>N</EM> and <EM>D</EM>, we can perform rational resampling
00054  * where <EM>N/D</EM> is a rational number close to the input rate
00055  * <EM>r</EM> where we have <EM>N</EM> filters and we cycle through
00056  * them as a polyphase filterbank with a stride of <EM>D</EM> so that
00057  * <EM>i+1 = (i + D) % N</EM>.
00058  *
00059  * To get the arbitrary rate, we want to interpolate between two
00060  * points. For each value out, we take an output from the current
00061  * filter, <EM>i</EM>, and the next filter <EM>i+1</EM> and then
00062  * linearly interpolate between the two based on the real resampling
00063  * rate we want.
00064  *
00065  * The linear interpolation only provides us with an approximation to
00066  * the real sampling rate specified. The error is a quantization error
00067  * between the two filters we used as our interpolation points.  To
00068  * this end, the number of filters, <EM>N</EM>, used determines the
00069  * quantization error; the larger <EM>N</EM>, the smaller the
00070  * noise. You can design for a specified noise floor by setting the
00071  * filter size (parameters <EM>filter_size</EM>). The size defaults to
00072  * 32 filters, which is about as good as most implementations need.
00073  *
00074  * The trick with designing this filter is in how to specify the taps
00075  * of the prototype filter. Like the PFB interpolator, the taps are
00076  * specified using the interpolated filter rate. In this case, that
00077  * rate is the input sample rate multiplied by the number of filters
00078  * in the filterbank, which is also the interpolation rate. All other
00079  * values should be relative to this rate.
00080  *
00081  * For example, for a 32-filter arbitrary resampler and using the
00082  * GNU Radio's firdes utility to build the filter, we build a low-pass
00083  * filter with a sampling rate of <EM>fs</EM>, a 3-dB bandwidth of
00084  * <EM>BW</EM> and a transition bandwidth of <EM>TB</EM>. We can also
00085  * specify the out-of-band attenuation to use, <EM>ATT</EM>, and the
00086  * filter window function (a Blackman-harris window in this case). The
00087  * first input is the gain of the filter, which we specify here as the
00088  * interpolation rate (<EM>32</EM>).
00089  *
00090  *      <B><EM>self._taps = gr.firdes.low_pass_2(32, 32*fs, BW, TB, 
00091  *           attenuation_dB=ATT, window=gr.firdes.WIN_BLACKMAN_hARRIS)</EM></B>
00092  *
00093  * The theory behind this block can be found in Chapter 7.5 of 
00094  * the following book.
00095  *
00096  *    <B><EM>f. harris, "Multirate Signal Processing for Communication 
00097  *       Systems", Upper Saddle River, NJ: Prentice Hall, Inc. 2004.</EM></B>
00098  */
00099 
00100 class GR_CORE_API gr_pfb_arb_resampler_ccf : public gr_block
00101 {
00102  private:
00103   /*!
00104    * Build the polyphase filterbank arbitray resampler.
00105    * \param rate  (float) Specifies the resampling rate to use
00106    * \param taps  (vector/list of floats) The prototype filter to populate the filterbank. The taps
00107    *                                      should be generated at the filter_size sampling rate.
00108    * \param filter_size (unsigned int) The number of filters in the filter bank. This is directly
00109                                        related to quantization noise introduced during the resampling.
00110                                        Defaults to 32 filters.
00111    */
00112   friend GR_CORE_API gr_pfb_arb_resampler_ccf_sptr gr_make_pfb_arb_resampler_ccf (float rate,
00113                                                                       const std::vector<float> &taps,
00114                                                                       unsigned int filter_size);
00115 
00116   std::vector<gr_fir_ccf*> d_filters;
00117   std::vector<gr_fir_ccf*> d_diff_filters;
00118   std::vector< std::vector<float> > d_taps;
00119   std::vector< std::vector<float> > d_dtaps;
00120   unsigned int             d_int_rate;          // the number of filters (interpolation rate)
00121   unsigned int             d_dec_rate;          // the stride through the filters (decimation rate)
00122   float                    d_flt_rate;          // residual rate for the linear interpolation
00123   float                    d_acc;
00124   unsigned int             d_last_filter;
00125   int                      d_start_index;
00126   unsigned int             d_taps_per_filter;
00127   bool                     d_updated;
00128 
00129   /*!
00130    * Build the polyphase filterbank arbitray resampler.
00131    * \param rate  (float) Specifies the resampling rate to use
00132    * \param taps  (vector/list of floats) The prototype filter to populate the filterbank. The taps
00133    *                                      should be generated at the filter_size sampling rate.
00134    * \param filter_size (unsigned int) The number of filters in the filter bank. This is directly
00135                                        related to quantization noise introduced during the resampling.
00136                                        Defaults to 32 filters.
00137    */
00138   gr_pfb_arb_resampler_ccf (float rate, 
00139                             const std::vector<float> &taps,
00140                             unsigned int filter_size);
00141 
00142   void create_diff_taps(const std::vector<float> &newtaps,
00143                         std::vector<float> &difftaps);
00144 
00145   /*!
00146    * Resets the filterbank's filter taps with the new prototype filter
00147    * \param newtaps    (vector of floats) The prototype filter to populate the filterbank. 
00148    *                   The taps should be generated at the interpolated sampling rate.
00149    * \param ourtaps    (vector of floats) Reference to our internal member of holding the taps.
00150    * \param ourfilter  (vector of filters) Reference to our internal filter to set the taps for.
00151    */
00152   void create_taps (const std::vector<float> &newtaps,
00153                     std::vector< std::vector<float> > &ourtaps,
00154                     std::vector<gr_fir_ccf*> &ourfilter);
00155 
00156   
00157 public:
00158   ~gr_pfb_arb_resampler_ccf ();
00159 
00160   // FIXME: See about a set_taps function during runtime.
00161 
00162   /*!
00163    * Print all of the filterbank taps to screen.
00164    */
00165   void print_taps();
00166   void set_rate (float rate) { 
00167     d_dec_rate = (unsigned int)floor(d_int_rate/rate);
00168     d_flt_rate = (d_int_rate/rate) - d_dec_rate;
00169     set_relative_rate(rate);
00170   }
00171 
00172   int general_work (int noutput_items,
00173                     gr_vector_int &ninput_items,
00174                     gr_vector_const_void_star &input_items,
00175                     gr_vector_void_star &output_items);
00176 };
00177 
00178 #endif