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