OpenShot Library | OpenShotAudio  0.2.1
juce_FilterDesign.h
1 
2 /** @weakgroup juce_dsp-filter_design
3  * @{
4  */
5 /*
6  ==============================================================================
7 
8  This file is part of the JUCE library.
9  Copyright (c) 2017 - ROLI Ltd.
10 
11  JUCE is an open source library subject to commercial or open-source
12  licensing.
13 
14  By using JUCE, you agree to the terms of both the JUCE 5 End-User License
15  Agreement and JUCE 5 Privacy Policy (both updated and effective as of the
16  27th April 2017).
17 
18  End User License Agreement: www.juce.com/juce-5-licence
19  Privacy Policy: www.juce.com/juce-5-privacy-policy
20 
21  Or: You may also use this code under the terms of the GPL v3 (see
22  www.gnu.org/licenses).
23 
24  JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
25  EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
26  DISCLAIMED.
27 
28  ==============================================================================
29 */
30 
31 namespace juce
32 {
33 namespace dsp
34 {
35 
36 /**
37  This class provides a set of functions which generates FIR::Coefficients
38  and IIR::Coefficients, of high-order low-pass filters. They can be used
39  for processing directly audio as an equalizer, in resampling algorithms etc.
40 
41  see FIRFilter::Coefficients, FIRFilter, WindowingFunction, IIRFilter::Coefficients, IIRFilter
42 
43  @tags{DSP}
44 */
45 template <typename FloatType>
47 {
48  using FIRCoefficientsPtr = typename FIR::Coefficients<FloatType>::Ptr;
49  using IIRCoefficients = typename IIR::Coefficients<FloatType>;
50 
51  using WindowingMethod = typename WindowingFunction<FloatType>::WindowingMethod;
52 
53  //==============================================================================
54  /** This method generates a FIR::Coefficients for a low-pass filter, using
55  the windowing design method, applied to a sinc impulse response. It is one
56  of the simplest method used to generate a high order low-pass filter, which
57  has the downside of needing more coefficients than more complex method to
58  perform a given attenuation in the stop band.
59 
60  It generates linear phase filters coefficients.
61 
62  Note: The flatTop WindowingMethod generates an impulse response with a
63  maximum amplitude higher than one, and might be normalised if necessary
64  depending on the applications.
65 
66  @param frequency the cutoff frequency of the low-pass filter
67  @param sampleRate the sample rate being used in the filter design
68  @param order the order of the filter
69  @param type the type, must be a WindowingFunction::WindowingType
70  @param beta an optional additional parameter useful for the Kaiser windowing function
71  */
72 
73  static FIRCoefficientsPtr designFIRLowpassWindowMethod (FloatType frequency, double sampleRate,
74  size_t order, WindowingMethod type,
75  FloatType beta = static_cast<FloatType> (2));
76 
77  /** This a variant of the function designFIRLowpassWindowMethod, which allows the
78  user to specify a transition width and a negative gain in dB,
79  to get a low-pass filter using the Kaiser windowing function, with calculated
80  values of the filter order and of the beta parameter, to satisfy the constraints.
81 
82  It generates linear phase filters coefficients.
83 
84  @param frequency the cutoff frequency of the low-pass filter
85  @param sampleRate the sample rate being used in the filter design
86  @param normalisedTransitionWidth the normalised size between 0 and 0.5 of the transition
87  between the pass band and the stop band
88  @param amplitudedB the maximum amplitude in dB expected in the stop band (must be negative)
89  */
90 
91  static FIRCoefficientsPtr designFIRLowpassKaiserMethod (FloatType frequency, double sampleRate,
92  FloatType normalisedTransitionWidth,
93  FloatType amplitudedB);
94 
95 
96  /** This method is also a variant of the function designFIRLowpassWindowMethod, using
97  a rectangular window as a basis, and a spline transition between the pass band and
98  the stop band, to reduce the Gibbs phenomenon.
99 
100  It generates linear phase filters coefficients.
101 
102  @param frequency the cutoff frequency of the low-pass filter
103  @param sampleRate the sample rate being used in the filter design
104  @param order the order of the filter
105  @param normalisedTransitionWidth the normalised size between 0 and 0.5 of the transition
106  between the pass band and the stop band
107  @param spline between 1.0 and 4.0, indicates how much the transition
108  is curved, with 1.0 meaning a straight line
109  */
110  static FIRCoefficientsPtr designFIRLowpassTransitionMethod (FloatType frequency, double sampleRate,
111  size_t order,
112  FloatType normalisedTransitionWidth,
113  FloatType spline);
114 
115  /** This method generates a FIR::Coefficients for a low-pass filter, by
116  minimizing the average error between the generated filter and an ideal one
117  using the least squares error criterion and matrices operations.
118 
119  It generates linear phase filters coefficients.
120 
121  @param frequency the cutoff frequency of the low-pass filter
122  @param sampleRate the sample rate being used in the filter design
123  @param order the order of the filter
124  @param normalisedTransitionWidth the normalised size between 0 and 0.5 of the transition
125  between the pass band and the stop band
126  @param stopBandWeight between 1.0 and 100.0, indicates how much we want
127  attenuation in the stop band, against some oscillation
128  in the pass band
129  */
130  static FIRCoefficientsPtr designFIRLowpassLeastSquaresMethod (FloatType frequency, double sampleRate, size_t order,
131  FloatType normalisedTransitionWidth,
132  FloatType stopBandWeight);
133 
134  /** This method generates a FIR::Coefficients for a low-pass filter, with
135  a cutoff frequency at half band, using an algorithm described in the article
136  "Design of Half-Band FIR Filters for Signal Compression" from Pavel
137  Zahradnik, to get an equiripple like high order FIR filter, without the need
138  of an iterative method and convergence failure risks.
139 
140  It generates linear phase filters coefficients.
141 
142  @param normalisedTransitionWidth the normalised size between 0 and 0.5 of the transition
143  between the pass band and the stop band
144  @param amplitudedB the maximum amplitude in dB expected in the stop band (must be negative)
145  */
146  static FIRCoefficientsPtr designFIRLowpassHalfBandEquirippleMethod (FloatType normalisedTransitionWidth,
147  FloatType amplitudedB);
148 
149  //==============================================================================
150  /** This method returns an array of IIR::Coefficients, made to be used in
151  cascaded IIRFilters, providing a minimum phase low-pass filter without any
152  ripple in the pass band and in the stop band.
153 
154  The algorithms are based on "Lecture Notes on Elliptic Filter Design" by
155  Sophocles J. Orfanidis.
156 
157  @param frequency the cutoff frequency of the low-pass filter
158  @param sampleRate the sample rate being used in the filter design
159  @param normalisedTransitionWidth the normalised size between 0 and 0.5 of the transition
160  between the pass band and the stop band
161  @param passbandAmplitudedB the highest gain in dB expected in the pass band (must be negative)
162  @param stopbandAmplitudedB the gain in dB expected in the stop band (must be negative)
163  */
164 
165  static ReferenceCountedArray<IIRCoefficients> designIIRLowpassHighOrderButterworthMethod (FloatType frequency, double sampleRate,
166  FloatType normalisedTransitionWidth,
167  FloatType passbandAmplitudedB,
168  FloatType stopbandAmplitudedB);
169 
170  //==============================================================================
171  /** This method returns an array of IIR::Coefficients, made to be used in
172  cascaded IIRFilters, providing a minimum phase low-pass filter without any
173  ripple in the pass band and in the stop band.
174 
175  @param frequency the cutoff frequency of the low-pass filter
176  @param sampleRate the sample rate being used in the filter design
177  @param order the order of the resulting IIR filter, providing
178  an attenuation of -6 dB times order / octave
179  */
180 
181  static ReferenceCountedArray<IIRCoefficients> designIIRLowpassHighOrderButterworthMethod (FloatType frequency, double sampleRate,
182  int order);
183 
184  /** This method returns an array of IIR::Coefficients, made to be used in
185  cascaded IIRFilters, providing a minimum phase high-pass filter without any
186  ripple in the pass band and in the stop band.
187 
188  @param frequency the cutoff frequency of the high-pass filter
189  @param sampleRate the sample rate being used in the filter design
190  @param order the order of the resulting IIR filter, providing
191  an attenuation of -6 dB times order / octave
192  */
193 
194  static ReferenceCountedArray<IIRCoefficients> designIIRHighpassHighOrderButterworthMethod (FloatType frequency, double sampleRate,
195  int order);
196 
197  /** This method returns an array of IIR::Coefficients, made to be used in
198  cascaded IIRFilters, providing a minimum phase low-pass filter without any
199  ripple in the stop band only.
200 
201  The algorithms are based on "Lecture Notes on Elliptic Filter Design" by
202  Sophocles J. Orfanidis.
203 
204  @param frequency the cutoff frequency of the low-pass filter
205  @param sampleRate the sample rate being used in the filter design
206  @param normalisedTransitionWidth the normalised size between 0 and 0.5 of the transition
207  between the pass band and the stop band
208  @param passbandAmplitudedB the highest amplitude in dB expected in the pass band (must be negative)
209  @param stopbandAmplitudedB the lowest amplitude in dB expected in the stop band (must be negative)
210  */
211  static ReferenceCountedArray<IIRCoefficients> designIIRLowpassHighOrderChebyshev1Method (FloatType frequency, double sampleRate,
212  FloatType normalisedTransitionWidth,
213  FloatType passbandAmplitudedB,
214  FloatType stopbandAmplitudedB);
215 
216  /** This method returns an array of IIR::Coefficients, made to be used in
217  cascaded IIRFilters, providing a minimum phase low-pass filter without any
218  ripple in the pass band only.
219 
220  The algorithms are based on "Lecture Notes on Elliptic Filter Design" by
221  Sophocles J. Orfanidis.
222 
223  @param frequency the cutoff frequency of the low-pass filter
224  @param sampleRate the sample rate being used in the filter design
225  @param normalisedTransitionWidth the normalised size between 0 and 0.5 of the transition
226  between the pass band and the stop band
227  @param passbandAmplitudedB the highest amplitude in dB expected in the pass band (must be negative)
228  @param stopbandAmplitudedB the lowest amplitude in dB expected in the stop band (must be negative)
229  */
230  static ReferenceCountedArray<IIRCoefficients> designIIRLowpassHighOrderChebyshev2Method (FloatType frequency, double sampleRate,
231  FloatType normalisedTransitionWidth,
232  FloatType passbandAmplitudedB,
233  FloatType stopbandAmplitudedB);
234 
235  /** This method returns an array of IIR::Coefficients, made to be used in
236  cascaded IIR::Filters, providing a minimum phase low-pass filter with ripples
237  in both the pass band and in the stop band.
238 
239  The algorithms are based on "Lecture Notes on Elliptic Filter Design" by
240  Sophocles J. Orfanidis.
241 
242  @param frequency the cutoff frequency of the low-pass filter
243  @param sampleRate the sample rate being used in the filter design
244  @param normalisedTransitionWidth the normalised size between 0 and 0.5 of the transition
245  between the pass band and the stop band
246  @param passbandAmplitudedB the highest amplitude in dB expected in the pass band (must be negative)
247  @param stopbandAmplitudedB the lowest amplitude in dB expected in the stop band (must be negative)
248  */
249  static ReferenceCountedArray<IIRCoefficients> designIIRLowpassHighOrderEllipticMethod (FloatType frequency, double sampleRate,
250  FloatType normalisedTransitionWidth,
251  FloatType passbandAmplitudedB,
252  FloatType stopbandAmplitudedB);
253 
254  /** The structure returned by the function designIIRLowpassHalfBandPolyphaseAllpassMethod.
255 
256  The two first members of this structure directPath and delayedPath are arrays of
257  IIR::Coefficients, made of polyphase second order allpass filters and an additional
258  delay in the second array, that can be used in cascaded filters processed in two
259  parallel paths, which must be summed at the end to get the high order efficient
260  low-pass filtering. The last member is an array with the useful parameters for
261  simulating the structure using any custom processing function.
262  */
264  {
265  ReferenceCountedArray<IIRCoefficients> directPath, delayedPath;
266  Array<double> alpha;
267  };
268 
269  /** This method generates arrays of IIR::Coefficients for a low-pass filter, with
270  a cutoff frequency at half band, using an algorithm described in the article
271  "Digital Signal Processing Schemes for efficient interpolation and decimation" from
272  Pavel Valenzuela and Constantinides.
273 
274  The result is a IIRPolyphaseAllpassStructure object.
275 
276  The two members of this structure directPath and delayedPath are arrays of
277  IIR::Coefficients, made of polyphase second order allpass filters and an additional
278  delay in the second array, that can be used in cascaded filters processed in two
279  parallel paths, which must be summed at the end to get the high order efficient
280  low-pass filtering.
281 
282  The gain of the resulting pass-band is 6 dB, so don't forget to compensate it if you
283  want to use that method for something else than two times oversampling.
284 
285  @param normalisedTransitionWidth the normalised size between 0 and 0.5 of the transition
286  between the pass band and the stop band
287  @param stopbandAmplitudedB the maximum amplitude in dB expected in the stop band (must be negative)
288  */
289  static IIRPolyphaseAllpassStructure designIIRLowpassHalfBandPolyphaseAllpassMethod (FloatType normalisedTransitionWidth,
290  FloatType stopbandAmplitudedB);
291 
292 private:
293  //==============================================================================
294  static Array<double> getPartialImpulseResponseHn (int n, double kp);
295 
296  static ReferenceCountedArray<IIRCoefficients> designIIRLowpassHighOrderGeneralMethod (int type, FloatType frequency, double sampleRate,
297  FloatType normalisedTransitionWidth,
298  FloatType passbandAmplitudedB,
299  FloatType stopbandAmplitudedB);
300  FilterDesign() = delete;
301 };
302 
303 } // namespace dsp
304 } // namespace juce
305 
306 /** @}*/
static ReferenceCountedArray< IIRCoefficients > designIIRLowpassHighOrderChebyshev1Method(FloatType frequency, double sampleRate, FloatType normalisedTransitionWidth, FloatType passbandAmplitudedB, FloatType stopbandAmplitudedB)
This method returns an array of IIR::Coefficients, made to be used in cascaded IIRFilters, providing a minimum phase low-pass filter without any ripple in the stop band only.
static ReferenceCountedArray< IIRCoefficients > designIIRLowpassHighOrderEllipticMethod(FloatType frequency, double sampleRate, FloatType normalisedTransitionWidth, FloatType passbandAmplitudedB, FloatType stopbandAmplitudedB)
This method returns an array of IIR::Coefficients, made to be used in cascaded IIR::Filters, providing a minimum phase low-pass filter with ripples in both the pass band and in the stop band.
static ReferenceCountedArray< IIRCoefficients > designIIRLowpassHighOrderChebyshev2Method(FloatType frequency, double sampleRate, FloatType normalisedTransitionWidth, FloatType passbandAmplitudedB, FloatType stopbandAmplitudedB)
This method returns an array of IIR::Coefficients, made to be used in cascaded IIRFilters, providing a minimum phase low-pass filter without any ripple in the pass band only.
static IIRPolyphaseAllpassStructure designIIRLowpassHalfBandPolyphaseAllpassMethod(FloatType normalisedTransitionWidth, FloatType stopbandAmplitudedB)
This method generates arrays of IIR::Coefficients for a low-pass filter, with a cutoff frequency at h...
WindowingMethod
The windowing methods available.
static FIRCoefficientsPtr designFIRLowpassLeastSquaresMethod(FloatType frequency, double sampleRate, size_t order, FloatType normalisedTransitionWidth, FloatType stopBandWeight)
This method generates a FIR::Coefficients for a low-pass filter, by minimizing the average error betw...
static FIRCoefficientsPtr designFIRLowpassTransitionMethod(FloatType frequency, double sampleRate, size_t order, FloatType normalisedTransitionWidth, FloatType spline)
This method is also a variant of the function designFIRLowpassWindowMethod, using a rectangular windo...
A set of coefficients for use in an Filter object.
static FIRCoefficientsPtr designFIRLowpassWindowMethod(FloatType frequency, double sampleRate, size_t order, WindowingMethod type, FloatType beta=static_cast< FloatType >(2))
This method generates a FIR::Coefficients for a low-pass filter, using the windowing design method...
static FIRCoefficientsPtr designFIRLowpassHalfBandEquirippleMethod(FloatType normalisedTransitionWidth, FloatType amplitudedB)
This method generates a FIR::Coefficients for a low-pass filter, with a cutoff frequency at half band...
A smart-pointer class which points to a reference-counted object.
static ReferenceCountedArray< IIRCoefficients > designIIRLowpassHighOrderButterworthMethod(FloatType frequency, double sampleRate, FloatType normalisedTransitionWidth, FloatType passbandAmplitudedB, FloatType stopbandAmplitudedB)
This method returns an array of IIR::Coefficients, made to be used in cascaded IIRFilters, providing a minimum phase low-pass filter without any ripple in the pass band and in the stop band.
The structure returned by the function designIIRLowpassHalfBandPolyphaseAllpassMethod.
This class provides a set of functions which generates FIR::Coefficients and IIR::Coefficients, of high-order low-pass filters.
static FIRCoefficientsPtr designFIRLowpassKaiserMethod(FloatType frequency, double sampleRate, FloatType normalisedTransitionWidth, FloatType amplitudedB)
This a variant of the function designFIRLowpassWindowMethod, which allows the user to specify a trans...
static ReferenceCountedArray< IIRCoefficients > designIIRHighpassHighOrderButterworthMethod(FloatType frequency, double sampleRate, int order)
This method returns an array of IIR::Coefficients, made to be used in cascaded IIRFilters, providing a minimum phase high-pass filter without any ripple in the pass band and in the stop band.