gr-fft: cleanup window related code

Updates some documentation, and adds bindings for tukey and gaussian windows which had not been included when they were added

Signed-off-by: Jacob Gilbert <jacob.gilbert@protonmail.com>

4 files changed, 70 insertions, 41 deletions

diff --git a/gr-fft/include/gnuradio/fft/window.h b/gr-fft/include/gnuradio/fft/window.h
index 8ef85d758..ab71b2a48 100644
--- a/gr-fft/include/gnuradio/fft/window.h
+++ b/gr-fft/include/gnuradio/fft/window.h
@@ -197,9 +197,17 @@ public:
     static std::vector<float> blackmanharris(int ntaps, int atten = 92);
 
     /*!
-     * \brief Build a Nuttall (or Blackman-Nuttall) window.
+     * \brief Build a minimum 4-term Nuttall (or Blackman-Nuttall) window, referred to by
+     * Heinzel G. et al. as a Nuttall4c window.
      *
-     * See: http://en.wikipedia.org/wiki/Window_function#Blackman.E2.80.93Nuttall_window
+     * See: A.H. Nuttall: 'Some windows with very good sidelobe behaviour', IEEE Trans. on
+     * Acoustics, Speech and Signal Processing, Vol ASSP-29, figure 15
+     *
+     * See: 'Spectrum and spectral density estimation by the Discrete Fourier transform
+     * (DFT), including a comprehensive list of window functions and some new flat-top
+     * windows', February 15, 2002 https://holometer.fnal.gov/GH_FFT.pdf
+     *
+     * Also: http://en.wikipedia.org/wiki/Window_function#Blackman.E2.80.93Nuttall_window
      *
      * \param ntaps Number of coefficients in the window.
      */
@@ -223,9 +231,17 @@ public:
     static std::vector<float> blackman_nuttal(int ntaps);
 
     /*!
-     * \brief Build a Nuttall continuous first derivative window.
+     * \brief Build a Nuttall 4-term continuous first derivative window, referred to by
+     * Heinzel G. et al. as a Nuttall4b window
      *
-     * See:
+     * See: A.H. Nuttall: 'Some windows with very good sidelobe behaviour', IEEE Trans. on
+     * Acoustics, Speech and Signal Processing, Vol ASSP-29, figure 12
+     *
+     * See: 'Spectrum and spectral density estimation by the Discrete Fourier transform
+     * (DFT), including a comprehensive list of window functions and some new flat-top
+     * windows', February 15, 2002 https://holometer.fnal.gov/GH_FFT.pdf
+     *
+     * Also:
      * http://en.wikipedia.org/wiki/Window_function#Nuttall_window.2C_continuous_first_derivative
      *
      * \param ntaps Number of coefficients in the window.
@@ -356,11 +372,14 @@ public:
      *
      * \param type a gr::fft::win_type index for the type of window.
      * \param ntaps Number of coefficients in the window.
-     * \param param Parameter value used for Kaiser (beta), Exponential (d), Gaussian (sigma) and Tukey (alpha) window creation.
-     * \param normalize If true, return a window with unit power
+     * \param param Parameter value used for Kaiser (beta), Exponential (d), Gaussian
+     * (sigma) and Tukey (alpha) window creation. \param normalize If true, return a
+     * window with unit power
      */
-    static std::vector<float>
-    build(win_type type, int ntaps, double param = INVALID_WIN_PARAM, const bool normalize = false);
+    static std::vector<float> build(win_type type,
+                                    int ntaps,
+                                    double param = INVALID_WIN_PARAM,
+                                    const bool normalize = false);
 };
 
 } /* namespace fft */
diff --git a/gr-fft/lib/window.cc b/gr-fft/lib/window.cc
index 98f0b897e..d79c62a74 100644
--- a/gr-fft/lib/window.cc
+++ b/gr-fft/lib/window.cc
@@ -1,6 +1,6 @@
 /* -*- c++ -*- */
 /*
- * Copyright 2002,2007,2008,2012,2013,2018 Free Software Foundation, Inc.
+ * Copyright 2002,2007,2008,2012,2013,2018,2021 Free Software Foundation, Inc.
  *
  * This file is part of GNU Radio
  *
@@ -55,28 +55,21 @@ double window::max_attenuation(win_type type, double param)
     switch (type) {
     case (WIN_HAMMING):
         return 53;
-        break;
     case (WIN_HANN):
         return 44;
-        break;
     case (WIN_BLACKMAN):
         return 74;
-        break;
     case (WIN_RECTANGULAR):
         return 21;
-        break;
     case (WIN_KAISER):
+        // linear approximation
         return (param / 0.1102 + 8.7);
-        break;
     case (WIN_BLACKMAN_hARRIS):
         return 92;
-        break;
     case (WIN_BARTLETT):
         return 27;
-        break;
     case (WIN_FLATTOP):
         return 93;
-        break;
     case WIN_NUTTALL:
         return 114;
     case WIN_NUTTALL_CFD:
@@ -91,7 +84,7 @@ double window::max_attenuation(win_type type, double param)
     case WIN_RIEMANN:
         return 39;
     case WIN_GAUSSIAN:
-        // not meaningful for gaussian windows, but return something reasonable
+        // value not meaningful for gaussian windows, but return something reasonable
         return 100;
     case WIN_TUKEY:
         // low end is a rectangular window, attenuation exponentialy approaches Hann
@@ -345,14 +338,14 @@ std::vector<float> window::riemann(int ntaps)
     return taps;
 }
 
-std::vector<float> window::tukey(int ntaps, float a)
+std::vector<float> window::tukey(int ntaps, float alpha)
 {
-    if ((a < 0) || (a > 1))
+    if ((alpha < 0) || (alpha > 1))
         throw std::out_of_range("window::tukey: alpha must be between 0 and 1");
 
     float N = static_cast<float>(ntaps - 1);
 
-    float aN = a * N;
+    float aN = alpha * N;
     float p1 = aN / 2.0;
     float mid = midn(ntaps);
     std::vector<float> taps(ntaps);
diff --git a/gr-fft/python/fft/bindings/docstrings/window_pydoc_template.h b/gr-fft/python/fft/bindings/docstrings/window_pydoc_template.h
index cc089b8c4..5988deb37 100644
--- a/gr-fft/python/fft/bindings/docstrings/window_pydoc_template.h
+++ b/gr-fft/python/fft/bindings/docstrings/window_pydoc_template.h
@@ -105,4 +105,10 @@ static const char* __doc_gr_fft_window_exponential = R"doc()doc";
 static const char* __doc_gr_fft_window_riemann = R"doc()doc";
 
 
+static const char* __doc_gr_fft_window_tukey = R"doc()doc";
+
+
+static const char* __doc_gr_fft_window_gaussian = R"doc()doc";
+
+
 static const char* __doc_gr_fft_window_build = R"doc()doc";
diff --git a/gr-fft/python/fft/bindings/window_python.cc b/gr-fft/python/fft/bindings/window_python.cc
index cc0fb6d58..6fb429022 100644
--- a/gr-fft/python/fft/bindings/window_python.cc
+++ b/gr-fft/python/fft/bindings/window_python.cc
@@ -14,7 +14,7 @@
 /* BINDTOOL_GEN_AUTOMATIC(0)                                                       */
 /* BINDTOOL_USE_PYGCCXML(0)                                                        */
 /* BINDTOOL_HEADER_FILE(window.h)                                                  */
-/* BINDTOOL_HEADER_FILE_HASH(de72e082a5bc1eeed7c4b3221025eb02)                     */
+/* BINDTOOL_HEADER_FILE_HASH(a44a323c53d5dd52382d240afdd4b984)                     */
 /***********************************************************************************/
 
 #include <pybind11/complex.h>
@@ -34,25 +34,25 @@ void bind_window(py::module& m)
     py::class_<window, std::shared_ptr<window>> window_class(m, "window", D(window));
 
     py::enum_<gr::fft::window::win_type>(window_class, "win_type")
-        .value("WIN_HAMMING", gr::fft::window::WIN_HAMMING)                     // 0
-        .value("WIN_HANN", gr::fft::window::WIN_HANN)                           // 1
-        .value("WIN_HANNING", gr::fft::window::WIN_HANNING)                     // 1
-        .value("WIN_BLACKMAN", gr::fft::window::WIN_BLACKMAN)                   // 2
-        .value("WIN_RECTANGULAR", gr::fft::window::WIN_RECTANGULAR)             // 3
-        .value("WIN_KAISER", gr::fft::window::WIN_KAISER)                       // 4
-        .value("WIN_BLACKMAN_hARRIS", gr::fft::window::WIN_BLACKMAN_hARRIS)     // 5
-        .value("WIN_BLACKMAN_HARRIS", gr::fft::window::WIN_BLACKMAN_HARRIS)     // 5
-        .value("WIN_BARTLETT", gr::fft::window::WIN_BARTLETT)                   // 6
-        .value("WIN_FLATTOP", gr::fft::window::WIN_FLATTOP)                     // 7
-        .value("WIN_NUTTALL", gr::fft::window::WIN_NUTTALL)                     // 8
-        .value("WIN_BLACKMAN_NUTTALL", gr::fft::window::WIN_BLACKMAN_NUTTALL)   // 8
-        .value("WIN_NUTTALL_CFD", gr::fft::window::WIN_NUTTALL_CFD)             // 9
-        .value("WIN_WELCH", gr::fft::window::WIN_WELCH)                         // 10
-        .value("WIN_PARZEN", gr::fft::window::WIN_PARZEN)                       // 11
-        .value("WIN_EXPONENTIAL", gr::fft::window::WIN_EXPONENTIAL)             // 12
-        .value("WIN_RIEMANN", gr::fft::window::WIN_RIEMANN)                     // 13
-        .value("WIN_GAUSSIAN", gr::fft::window::WIN_GAUSSIAN)                   // 14
-        .value("WIN_TUKEY", gr::fft::window::WIN_TUKEY)                         // 15
+        .value("WIN_HAMMING", gr::fft::window::WIN_HAMMING)                   // 0
+        .value("WIN_HANN", gr::fft::window::WIN_HANN)                         // 1
+        .value("WIN_HANNING", gr::fft::window::WIN_HANNING)                   // 1
+        .value("WIN_BLACKMAN", gr::fft::window::WIN_BLACKMAN)                 // 2
+        .value("WIN_RECTANGULAR", gr::fft::window::WIN_RECTANGULAR)           // 3
+        .value("WIN_KAISER", gr::fft::window::WIN_KAISER)                     // 4
+        .value("WIN_BLACKMAN_hARRIS", gr::fft::window::WIN_BLACKMAN_hARRIS)   // 5
+        .value("WIN_BLACKMAN_HARRIS", gr::fft::window::WIN_BLACKMAN_HARRIS)   // 5
+        .value("WIN_BARTLETT", gr::fft::window::WIN_BARTLETT)                 // 6
+        .value("WIN_FLATTOP", gr::fft::window::WIN_FLATTOP)                   // 7
+        .value("WIN_NUTTALL", gr::fft::window::WIN_NUTTALL)                   // 8
+        .value("WIN_BLACKMAN_NUTTALL", gr::fft::window::WIN_BLACKMAN_NUTTALL) // 8
+        .value("WIN_NUTTALL_CFD", gr::fft::window::WIN_NUTTALL_CFD)           // 9
+        .value("WIN_WELCH", gr::fft::window::WIN_WELCH)                       // 10
+        .value("WIN_PARZEN", gr::fft::window::WIN_PARZEN)                     // 11
+        .value("WIN_EXPONENTIAL", gr::fft::window::WIN_EXPONENTIAL)           // 12
+        .value("WIN_RIEMANN", gr::fft::window::WIN_RIEMANN)                   // 13
+        .value("WIN_GAUSSIAN", gr::fft::window::WIN_GAUSSIAN)                 // 14
+        .value("WIN_TUKEY", gr::fft::window::WIN_TUKEY)                       // 15
         .export_values();
 
     py::implicitly_convertible<int, gr::fft::window::win_type>();
@@ -194,6 +194,17 @@ void bind_window(py::module& m)
         .def_static("riemann", &window::riemann, py::arg("ntaps"), D(window, riemann))
 
 
+        .def_static(
+            "tukey", &window::tukey, py::arg("ntaps"), py::arg("alpha"), D(window, tukey))
+
+
+        .def_static("gaussian",
+                    &window::gaussian,
+                    py::arg("ntaps"),
+                    py::arg("sigma"),
+                    D(window, gaussian))
+
+
         .def_static("build",
                     &window::build,
                     py::arg("type"),