GNU Radio Manual and C++ API Reference 3.9.4.0
The Free & Open Software Radio Ecosystem
window.h
Go to the documentation of this file.
1/* -*- c++ -*- */
2/*
3 * Copyright 2002,2007,2008,2012,2013 Free Software Foundation, Inc.
4 *
5 * This file is part of GNU Radio
6 *
7 * SPDX-License-Identifier: GPL-3.0-or-later
8 *
9 */
10
11#ifndef INCLUDED_FFT_WINDOW_H
12#define INCLUDED_FFT_WINDOW_H
13
14#include <gnuradio/fft/api.h>
15#include <gnuradio/gr_complex.h>
16#include <cmath>
17#include <vector>
18
19namespace gr {
20namespace fft {
21
23{
24public:
25 enum win_type {
26 WIN_NONE = -1, //!< don't use a window
27 WIN_HAMMING = 0, //!< Hamming window; max attenuation 53 dB
28 WIN_HANN = 1, //!< Hann window; max attenuation 44 dB
29 WIN_HANNING = 1, //!< alias to WIN_HANN
30 WIN_BLACKMAN = 2, //!< Blackman window; max attenuation 74 dB
31 WIN_RECTANGULAR = 3, //!< Basic rectangular window; max attenuation 21 dB
32 WIN_KAISER = 4, //!< Kaiser window; max attenuation see window::max_attenuation
33 WIN_BLACKMAN_hARRIS = 5, //!< Blackman-harris window; max attenuation 92 dB
34 WIN_BLACKMAN_HARRIS =
35 5, //!< alias to WIN_BLACKMAN_hARRIS for capitalization consistency
36 WIN_BARTLETT = 6, //!< Barlett (triangular) window; max attenuation 26 dB
37 WIN_FLATTOP = 7, //!< flat top window; useful in FFTs; max attenuation 93 dB
38 WIN_NUTTALL = 8, //!< Nuttall window; max attenuation 114 dB
39 WIN_BLACKMAN_NUTTALL = 8, //!< Nuttall window; max attenuation 114 dB
40 WIN_NUTTALL_CFD =
41 9, //!< Nuttall continuous-first-derivative window; max attenuation 112 dB
42 WIN_WELCH = 10, //!< Welch window; max attenuation 31 dB
43 WIN_PARZEN = 11, //!< Parzen window; max attenuation 56 dB
44 WIN_EXPONENTIAL =
45 12, //!< Exponential window; max attenuation see window::max_attenuation
46 WIN_RIEMANN = 13, //!< Riemann window; max attenuation 39 dB
47 WIN_GAUSSIAN =
48 14, //!< Gaussian window; max attenuation see window::max_attenuation
49 WIN_TUKEY = 15, //!< Tukey window; max attenuation see window::max_attenuation
50 };
51
52 /*!
53 * \brief Given a window::win_type, this tells you the maximum
54 * attenuation (really the maximum approximation error) you can expect.
55 *
56 * \details
57 * For most windows, this is a set value. For the Kaiser, Exponential, Gaussian, and
58 * Tukey windows, the attenuation is based on the value of a provided parameter.
59 *
60 * For the Kaiser window the actual relationship is a piece-wise exponential
61 * relationship to calculate beta from the desired attenuation and can be found on
62 * page 542 of Oppenheim and Schafer (Discrete-Time Signal Processing, 3rd edition).
63 * To simplify this function to solve for A given beta, we use a linear form that is
64 * exact for attenuation >= 50 dB. For an attenuation of 50 dB, beta = 4.55; for an
65 * attenuation of 70 dB, beta = 6.76.
66 *
67 * Exponential attenuation is complicated to measure due to the irregular error ripple
68 * structure, but it ranges between 23 and 26 dB depending on the decay factor; 26 dB
69 * is a good bound.
70 *
71 * The Gaussian window should not be used for window based filter construction;
72 * instead there is a dedicated gaussian filter construction fuction. There is no
73 * meaningful way to measure approximation error 'delta' as shown in Fig 7.23 of
74 * Oppenheim and Schafer (Discrete-Time Signal Processing, 3rd edition).
75 *
76 * Tukey windows provide attenuation that varies non-linearily between Rectangular (21
77 * dB) and Hann (44 dB) windows.
78 *
79 * \param type The window::win_type enumeration of the window type.
80 * \param beta Parameter value used for Kaiser (beta), Exponential (d), Gaussian
81 * (sigma) and Tukey (alpha) window creation. The name `beta` is still used for API
82 * compatibility reasons but will be changed to `param` in 3.10.
83 */
84 static double max_attenuation(win_type type, double beta = 6.76);
85
86 /*!
87 * \brief Helper function to build cosine-based windows. 3-coefficient version.
88 */
89 static std::vector<float> coswindow(int ntaps, float c0, float c1, float c2);
90
91 /*!
92 * \brief Helper function to build cosine-based windows. 4-coefficient version.
93 */
94 static std::vector<float>
95 coswindow(int ntaps, float c0, float c1, float c2, float c3);
96
97 /*!
98 * \brief Helper function to build cosine-based windows. 5-coefficient version.
99 */
100 static std::vector<float>
101 coswindow(int ntaps, float c0, float c1, float c2, float c3, float c4);
102
103 /*!
104 * \brief Build a rectangular window.
105 *
106 * Taps are flat across the window.
107 *
108 * \param ntaps Number of coefficients in the window.
109 */
110 static std::vector<float> rectangular(int ntaps);
111
112 /*!
113 * \brief Build a Hamming window.
114 *
115 * See:
116 * <pre>
117 * A. V. Oppenheim and R. W. Schafer, "Discrete-Time
118 * Signal Processing," Upper Saddle River, N.J.: Prentice
119 * Hall, 2010, pp. 535-538.
120 * </pre>
121 *
122 * \param ntaps Number of coefficients in the window.
123 */
124 static std::vector<float> hamming(int ntaps);
125
126 /*!
127 * \brief Build a Hann window (sometimes known as Hanning).
128 *
129 * See:
130 * <pre>
131 * A. V. Oppenheim and R. W. Schafer, "Discrete-Time
132 * Signal Processing," Upper Saddle River, N.J.: Prentice
133 * Hall, 2010, pp. 535-538.
134 * </pre>
135 *
136 * \param ntaps Number of coefficients in the window.
137 */
138 static std::vector<float> hann(int ntaps);
139
140 /*!
141 * \brief Alias to build a Hann window.
142 *
143 * \param ntaps Number of coefficients in the window.
144 */
145 static std::vector<float> hanning(int ntaps);
146
147 /*!
148 * \brief Build an exact Blackman window.
149 *
150 * See:
151 * <pre>
152 * A. V. Oppenheim and R. W. Schafer, "Discrete-Time
153 * Signal Processing," Upper Saddle River, N.J.: Prentice
154 * Hall, 2010, pp. 535-538.
155 * </pre>
156 *
157 * \param ntaps Number of coefficients in the window.
158 */
159 static std::vector<float> blackman(int ntaps);
160
161 /*!
162 * \brief Build Blackman window, variation 1.
163 */
164 static std::vector<float> blackman2(int ntaps);
165
166 /*!
167 * \brief Build Blackman window, variation 2.
168 */
169 static std::vector<float> blackman3(int ntaps);
170
171 /*!
172 * \brief Build Blackman window, variation 3.
173 */
174 static std::vector<float> blackman4(int ntaps);
175
176 /*!
177 * \brief Build a Blackman-harris window with a given attenuation.
178 *
179 * <pre>
180 * f. j. harris, "On the use of windows for harmonic analysis
181 * with the discrete Fourier transforms," Proc. IEEE, Vol. 66,
182 * ppg. 51-83, Jan. 1978.
183 * </pre>
184 *
185 * \param ntaps Number of coefficients in the window.
186
187 * \param atten Attenuation factor. Must be [61, 67, 74, 92].
188 * See the above paper for details.
189 */
190 static std::vector<float> blackman_harris(int ntaps, int atten = 92);
191
192 /*!
193 * Alias to gr::fft::window::blackman_harris.
194 */
195 static std::vector<float> blackmanharris(int ntaps, int atten = 92);
196
197 /*!
198 * \brief Build a minimum 4-term Nuttall (or Blackman-Nuttall) window, referred to by
199 * Heinzel G. et al. as a Nuttall4c window.
200 *
201 * See: A.H. Nuttall: 'Some windows with very good sidelobe behaviour', IEEE Trans. on
202 * Acoustics, Speech and Signal Processing, Vol ASSP-29, figure 15
203 *
204 * See: 'Spectrum and spectral density estimation by the Discrete Fourier transform
205 * (DFT), including a comprehensive list of window functions and some new flat-top
206 * windows', February 15, 2002 https://holometer.fnal.gov/GH_FFT.pdf
207 *
208 * Also: http://en.wikipedia.org/wiki/Window_function#Blackman.E2.80.93Nuttall_window
209 *
210 * \param ntaps Number of coefficients in the window.
211 */
212 static std::vector<float> nuttall(int ntaps);
213
214 /*!
215 * Deprecated: use nuttall window instead.
216 */
217 static std::vector<float> nuttal(int ntaps);
218
219 /*!
220 * \brief Alias to the Nuttall window.
221 *
222 * \param ntaps Number of coefficients in the window.
223 */
224 static std::vector<float> blackman_nuttall(int ntaps);
225
226 /*!
227 * Deprecated: use blackman_nuttall window instead.
228 */
229 static std::vector<float> blackman_nuttal(int ntaps);
230
231 /*!
232 * \brief Build a Nuttall 4-term continuous first derivative window, referred to by
233 * Heinzel G. et al. as a Nuttall4b window
234 *
235 * See: A.H. Nuttall: 'Some windows with very good sidelobe behaviour', IEEE Trans. on
236 * Acoustics, Speech and Signal Processing, Vol ASSP-29, figure 12
237 *
238 * See: 'Spectrum and spectral density estimation by the Discrete Fourier transform
239 * (DFT), including a comprehensive list of window functions and some new flat-top
240 * windows', February 15, 2002 https://holometer.fnal.gov/GH_FFT.pdf
241 *
242 * Also:
243 * http://en.wikipedia.org/wiki/Window_function#Nuttall_window.2C_continuous_first_derivative
244 *
245 * \param ntaps Number of coefficients in the window.
246 */
247 static std::vector<float> nuttall_cfd(int ntaps);
248
249 /*!
250 * Deprecated: use nuttall_cfd window instead.
251 */
252 static std::vector<float> nuttal_cfd(int ntaps);
253
254 /*!
255 * \brief Build a flat top window per the SRS specification
256 *
257 * See:
258 * <pre>
259 * Stanford Research Systems, "Model SR785 Dynamic Signal
260 * Analyzer: Operating Manual and Programming Reference,"
261 * 2017, pp 2-13
262 * </pre>
263 *
264 * Note: there are many flat top windows, and this implementation is different from
265 * SciPY and Matlab which use the coefficients from D’Antona et al. "Digital Signal
266 * Processing for Measurement Systems" with the following cosine coefficients: <pre>
267 * [0.21557895, 0.41663158, 0.277263158, 0.083578947, 0.006947368]
268 * </pre>
269 *
270 * \param ntaps Number of coefficients in the window.
271 */
272 static std::vector<float> flattop(int ntaps);
273
274 /*!
275 * \brief Build a Kaiser window with a given beta.
276 *
277 * See:
278 * <pre>
279 * A. V. Oppenheim and R. W. Schafer, "Discrete-Time
280 * Signal Processing," Upper Saddle River, N.J.: Prentice
281 * Hall, 2010, pp. 541-545.
282 * </pre>
283 *
284 * \param ntaps Number of coefficients in the window.
285 * \param beta Shaping parameter of the window. See the
286 * discussion in Oppenheim and Schafer.
287 */
288 static std::vector<float> kaiser(int ntaps, double beta);
289
290 /*!
291 * \brief Build a Barlett (triangular) window.
292 *
293 * See:
294 * <pre>
295 * A. V. Oppenheim and R. W. Schafer, "Discrete-Time
296 * Signal Processing," Upper Saddle River, N.J.: Prentice
297 * Hall, 2010, pp. 535-538.
298 * </pre>
299 *
300 * \param ntaps Number of coefficients in the window.
301 */
302 static std::vector<float> bartlett(int ntaps);
303
304 static std::vector<float> welch(int ntaps);
305
306 /*!
307 * \brief Build a Parzen (or de la Valle-Poussin) window.
308 *
309 * See:
310 * <pre>
311 * A. D. Poularikas, "Handbook of Formulas and Tables for
312 * Signal Processing," Springer, Oct 28, 1998
313 * </pre>
314 *
315 * \param ntaps Number of coefficients in the window.
316 */
317 static std::vector<float> parzen(int ntaps);
318
319 /*!
320 * \brief Build an exponential window with a given decay.
321 *
322 * See: http://en.wikipedia.org/wiki/Window_function#Exponential_or_Poisson_window
323 *
324 * \param ntaps Number of coefficients in the window.
325 * \param d Decay of \p d dB over half the window length.
326 */
327 static std::vector<float> exponential(int ntaps, double d);
328
329 /*!
330 * \brief Build a Riemann window.
331 *
332 * See:
333 * <pre>
334 * A. D. Poularikas, "Handbook of Formulas and Tables for
335 * Signal Processing," Springer, Oct 28, 1998
336 * </pre>
337 *
338 * \param ntaps Number of coefficients in the window.
339 */
340 static std::vector<float> riemann(int ntaps);
341
342 /*!
343 * \brief Build a Tukey window.
344 * <pre>
345 * Bloomfield, P. Fourier Analysis of Time Series: An Introduction. New York:
346 * Wiley-Interscience, 2000, pp 69 (eqn 6.9)
347 * </pre>
348 *
349 * \param ntaps Number of coefficients in the window.
350 * \param alpha Shaping parameter for the Tukey window, an
351 * alpha of zero is equivalent to a rectangular
352 * window, an alpha of 1 is equivalent to Hann.
353 */
354 static std::vector<float> tukey(int ntaps, float alpha);
355
356 /*!
357 * \brief Build a Gaussian window using the equation
358 * <pre>
359 * exp(-(1/2) * (n/sigma)^2)
360 * </pre>
361 *
362 * \param ntaps Number of coefficients in the window.
363 * \param sigma Standard deviation of gaussian distribution.
364 */
365 static std::vector<float> gaussian(int ntaps, float sigma);
366
367 /*!
368 * \brief Build a window using gr::fft::win_type to index the
369 * type of window desired.
370 *
371 * \param type a gr::fft::win_type index for the type of window.
372 * \param ntaps Number of coefficients in the window.
373 * \param beta Parameter value used for Kaiser (beta), Exponential (d), Gaussian
374 * (sigma) and Tukey (alpha) window creation. The name `beta` is still used for API
375 * compatibility reasons but will be changed to `param` in 3.10.
376 * \param normalize If true, return a window with unit power
377 */
378 static std::vector<float>
379 build(win_type type, int ntaps, double beta = 6.76, const bool normalize = false);
380};
381
382} /* namespace fft */
383} /* namespace gr */
384
385#endif /* INCLUDED_FFT_WINDOW_H */
Definition: window.h:23
static std::vector< float > gaussian(int ntaps, float sigma)
Build a Gaussian window using the equation.
static std::vector< float > blackman_harris(int ntaps, int atten=92)
Build a Blackman-harris window with a given attenuation.
static std::vector< float > coswindow(int ntaps, float c0, float c1, float c2, float c3, float c4)
Helper function to build cosine-based windows. 5-coefficient version.
static std::vector< float > blackman3(int ntaps)
Build Blackman window, variation 2.
static std::vector< float > blackman(int ntaps)
Build an exact Blackman window.
static std::vector< float > blackman2(int ntaps)
Build Blackman window, variation 1.
static std::vector< float > welch(int ntaps)
static std::vector< float > rectangular(int ntaps)
Build a rectangular window.
static std::vector< float > flattop(int ntaps)
Build a flat top window per the SRS specification.
static std::vector< float > blackmanharris(int ntaps, int atten=92)
static std::vector< float > blackman_nuttall(int ntaps)
Alias to the Nuttall window.
static std::vector< float > hann(int ntaps)
Build a Hann window (sometimes known as Hanning).
static std::vector< float > nuttal(int ntaps)
static std::vector< float > build(win_type type, int ntaps, double beta=6.76, const bool normalize=false)
Build a window using gr::fft::win_type to index the type of window desired.
win_type
Definition: window.h:25
static std::vector< float > hamming(int ntaps)
Build a Hamming window.
static std::vector< float > blackman_nuttal(int ntaps)
static std::vector< float > nuttal_cfd(int ntaps)
static std::vector< float > nuttall(int ntaps)
Build a minimum 4-term Nuttall (or Blackman-Nuttall) window, referred to by Heinzel G....
static std::vector< float > nuttall_cfd(int ntaps)
Build a Nuttall 4-term continuous first derivative window, referred to by Heinzel G....
static std::vector< float > coswindow(int ntaps, float c0, float c1, float c2, float c3)
Helper function to build cosine-based windows. 4-coefficient version.
static std::vector< float > hanning(int ntaps)
Alias to build a Hann window.
static std::vector< float > riemann(int ntaps)
Build a Riemann window.
static std::vector< float > blackman4(int ntaps)
Build Blackman window, variation 3.
static std::vector< float > kaiser(int ntaps, double beta)
Build a Kaiser window with a given beta.
static double max_attenuation(win_type type, double beta=6.76)
Given a window::win_type, this tells you the maximum attenuation (really the maximum approximation er...
static std::vector< float > coswindow(int ntaps, float c0, float c1, float c2)
Helper function to build cosine-based windows. 3-coefficient version.
static std::vector< float > tukey(int ntaps, float alpha)
Build a Tukey window.
static std::vector< float > parzen(int ntaps)
Build a Parzen (or de la Valle-Poussin) window.
static std::vector< float > exponential(int ntaps, double d)
Build an exponential window with a given decay.
static std::vector< float > bartlett(int ntaps)
Build a Barlett (triangular) window.
#define FFT_API
Definition: gr-fft/include/gnuradio/fft/api.h:18
GNU Radio logging wrapper for log4cpp library (C++ port of log4j)
Definition: basic_block.h:29