[Commit-gnuradio] [gnuradio] 12/13: filter: adds documentation to using the rational resamplers.

[git]

This is an automated email from the git hooks/post-receive script.

trondeau pushed a commit to branch maint
in repository gnuradio.

commit 9287d50214534b64cd4b2087a1b079233b05285e
Author: Tom Rondeau <address@hidden>
Date:   Wed Dec 3 13:27:49 2014 -0500

    filter: adds documentation to using the rational resamplers.
    
    If user provided taps, don't adjust values by the GCD since that will mean 
the provided filter is not valid. Only apply when the resampler designs its own 
filter.
---
 .../filter/rational_resampler_base_XXX.h.t         | 38 ++++++++++++++++++++++
 gr-filter/python/filter/rational_resampler.py      | 16 ++++++---
 2 files changed, 50 insertions(+), 4 deletions(-)

diff --git a/gr-filter/include/gnuradio/filter/rational_resampler_base_XXX.h.t 
b/gr-filter/include/gnuradio/filter/rational_resampler_base_XXX.h.t
index d4ea204..d5f8379 100644
--- a/gr-filter/include/gnuradio/filter/rational_resampler_base_XXX.h.t
+++ b/gr-filter/include/gnuradio/filter/rational_resampler_base_XXX.h.t
@@ -36,6 +36,37 @@ namespace gr {
      * \brief Rational Resampling Polyphase FIR filter with @I_TYPE@
      * input, @O_TYPE@ output and @TAP_TYPE@ taps.
      * \ingroup resamplers_blk
+     *
+     * Make a rational resampling FIR filter. If the input signal is
+     * at rate fs, then the output signal will be at a rate of \p
+     * interpolation * fs / \p decimation.
+     *
+     * The interpolation and decimation rates should be kept as
+     * small as possible, and generally should be relatively prime
+     * to help reduce complexity in memory and computation.
+     *
+     * The set of \p taps supplied to this filterbank should be
+     * designed around the resampling amount and must avoid aliasing
+     * (when interpolation/decimation < 1) and images (when
+     * interpolation/decimation > 1).
+     *
+     * As with any filter, the behavior of the filter taps (or
+     * coefficients) is determined by the highest sampling rate that
+     * the filter will ever see. In the case of a resampler that
+     * increases the sampling rate, the highest sampling rate observed
+     * is \p interpolation since in the filterbank, the number of
+     * filter arms is equal to \p interpolation. When the resampler
+     * decreases the sampling rate (decimation > interpolation), then
+     * the highest rate is the input sample rate of the original
+     * signal. We must create a filter based around this value to
+     * reduce any aliasing that may occur from out-of-band signals.
+     *
+     * Another way to think about how to create the filter taps is
+     * that the filter is effectively applied after interpolation and
+     * before decimation. And yet another way to think of it is that
+     * the taps should be a LPF that is at least as narrow as the
+     * narrower of the required anti-image postfilter or anti-alias
+     * prefilter.
      */
     class FILTER_API @NAME@ : virtual public block
     {
@@ -43,6 +74,13 @@ namespace gr {
       // gr::filter::@BASE_NAME@::sptr
       typedef boost::shared_ptr<@BASE_NAME@> sptr;
 
+      /*!
+       * Make a rational resampling FIR filter.
+       *
+       * \param interpolation The integer interpolation rate of the filter
+       * \param decimation The integer decimation rate of the filter
+       * \param taps The filter taps to control images and aliases
+       */
       static sptr make(unsigned interpolation,
                        unsigned decimation,
                        const std::vector<@TAP_TYPE@> &taps);
diff --git a/gr-filter/python/filter/rational_resampler.py 
b/gr-filter/python/filter/rational_resampler.py
index 32246a0..961ffc6 100644
--- a/gr-filter/python/filter/rational_resampler.py
+++ b/gr-filter/python/filter/rational_resampler.py
@@ -50,7 +50,6 @@ def design_filter(interpolation, decimation, fractional_bw):
         trans_width = rate*(halfband - fractional_bw)
         mid_transition_band = rate*halfband - trans_width/2.0
 
-    print trans_width, mid_transition_band
     taps = filter.firdes.low_pass(interpolation,                     # gain
                                   interpolation,                     # Fs
                                   mid_transition_band,               # trans 
mid point
@@ -58,7 +57,6 @@ def design_filter(interpolation, decimation, fractional_bw):
                                   filter.firdes.WIN_KAISER,
                                   beta)                              # beta
 
-    print len(taps)
     return taps
 
 
@@ -93,10 +91,20 @@ class _rational_resampler_base(gr.hier_block2):
             fractional_bw = 0.4
 
         d = gru.gcd(interpolation, decimation)
-        interpolation = interpolation // d
-        decimation = decimation // d
 
+        # If we have user-provided taps and the interp and decim
+        # values have a common divisor, we don't reduce these values
+        # by the GCD but issue a warning to the user that this might
+        # increase the complexity of the filter.
+        if taps and (d > 1):
+            gr.log.info("Rational resampler has user-provided taps but 
interpolation ({0}) and decimation ({1}) have a GCD of {2}, which increases the 
complexity of the filterbank. Consider reducing these values by the 
GCD.".format(interpolation, decimation, d))
+
+        # If we don't have user-provided taps, reduce the interp and
+        # decim values by the GCD (if there is one) and then define
+        # the taps from these new values.
         if taps is None:
+            interpolation = interpolation // d
+            decimation = decimation // d
             taps = design_filter(interpolation, decimation, fractional_bw)
 
         self.resampler = resampler_base(interpolation, decimation, taps)