spcore 0.1.2 → 0.1.3

data/lib/spcore/filters/fir/dual_sinc_filter.rb

@@ -0,0 +1,84 @@
+module SPCore
+
+# Extended windowed sinc filter. Implements bandpass and bandstop using
+# two SincFilterBase objects.
+#
+# Theoretical source: http://www.labbookpages.co.uk/audio/firWindowing.html
+#
+# @author James Tunnell
+#
+class DualSincFilter
+  include Hashmake::HashMakeable
+  
+  # Use to process hashed args in #initialize.
+  ARG_SPECS = [
+    Hashmake::ArgSpec.new(:key => :order, :reqd => true, :type => Fixnum, :validator => ->(a){ a % 2 == 0 } ),
+    Hashmake::ArgSpec.new(:key => :sample_rate, :reqd => true, :type => Numeric, :validator => ->(a){ a > 0.0 } ),
+    Hashmake::ArgSpec.new(:key => :left_cutoff_freq, :reqd => true, :type => Numeric, :validator => ->(a){ a > 0.0 } ),
+    Hashmake::ArgSpec.new(:key => :right_cutoff_freq, :reqd => true, :type => Numeric, :validator => ->(a){ a > 0.0 } ),
+    Hashmake::ArgSpec.new(:key => :window_class, :reqd => false, :type => Class, :default => BlackmanWindow ),
+  ]
+  
+  attr_reader :bandpass_fir, :bandstop_fir, :left_filter, :right_filter
+  
+  # Given a filter order, 2 cutoff frequencies, sample rate, and window class,
+  # develop a FIR filter kernel that can be used for lowpass filtering.
+  def initialize args
+    hash_make DualSincFilter::ARG_SPECS, args
+    
+    raise ArgumentError, "left_cutoff_freq is greater than 0.5 * sample_rate" if @left_cutoff_freq > (@sample_rate / 2)
+    raise ArgumentError, "right_cutoff_freq is greater than 0.5 * sample_rate" if @right_cutoff_freq > (@sample_rate / 2)
+    raise ArgumentError, "left_cutoff_freq is not less than right_cutoff_freq" unless @left_cutoff_freq < @right_cutoff_freq 
+    
+    @left_filter = SincFilter.new(
+      :sample_rate => @sample_rate,
+      :order => @order,
+      :cutoff_freq => @left_cutoff_freq,
+      :window_class => @window_class,
+    )
+
+    @right_filter = SincFilter.new(
+      :sample_rate => @sample_rate,
+      :order => @order,
+      :cutoff_freq => @right_cutoff_freq,
+      :window_class => @window_class,
+    )
+    
+    size = @order + 1
+
+    # make FIR filter kernels for bandpass and bandstop
+    
+    bandpass_kernel = Array.new(size)
+    bandstop_kernel = Array.new(size)
+    window = @window_class.new(size)
+    
+    for n in 0...(@order / 2)
+      bandpass_kernel[size - 1 - n] = bandpass_kernel[n] = @right_filter.lowpass_fir.kernel[n] + @left_filter.highpass_fir.kernel[n]
+      bandstop_kernel[size - 1 - n] = bandstop_kernel[n] = @left_filter.lowpass_fir.kernel[n] + @right_filter.highpass_fir.kernel[n]
+    end
+
+    left_transition_freq = @left_cutoff_freq / @sample_rate
+    right_transition_freq = @right_cutoff_freq / @sample_rate
+    bw_times_two = 2.0 * (right_transition_freq - left_transition_freq)
+    window_center_val = window.data[@order / 2]
+    
+    bandpass_kernel[@order / 2] = bw_times_two * window_center_val
+    bandstop_kernel[@order / 2] = (1.0 - bw_times_two) * window_center_val
+    
+    @bandpass_fir = FIR.new bandpass_kernel, @sample_rate
+    @bandstop_fir = FIR.new bandstop_kernel, @sample_rate
+  end
+
+  # Process the input with the bandpass FIR.
+  # @return [Array] containing the filtered input.  
+  def bandpass input
+    return @bandpass_fir.convolve input
+  end
+  
+  # Process the input with the bandstop FIR.
+  # @return [Array] containing the filtered input.
+  def bandstop input
+    return @bandstop_fir.convolve input
+  end
+end
+end

data/lib/spcore/filters/fir/fir.rb

@@ -0,0 +1,87 @@
+module SPCore
+# General FIR filter class. Contains the filter kernel and performs
+# convolution.
+class FIR
+  
+  attr_reader :kernel, :order, :sample_rate
+  
+  # A new instance of FIR. Filter order will by kernel size - 1.
+  # @param [Array] kernel Filter kernel values.
+  # @param [Numeric] sample_rate The sample rate the filter operates at.
+  def initialize kernel, sample_rate
+    @kernel = kernel
+    @order = kernel.size - 1
+    @sample_rate = sample_rate
+  end
+  
+  # Convolve the given input data with the filter kernel.
+  # @param [Array] input Array of input data to by convolved with filter kernel.
+  #                      The array size must be greater than the filter kernel size.
+  def convolve input
+    kernel_size = @kernel.size
+    raise ArgumentError, "input.size #{input.size} is not greater than filter kernel size #{kernel_size}" unless input.size > kernel_size
+    
+    output = Array.new(input.size, 0.0)
+
+    for i in 0...kernel_size
+      sum = 0.0
+      # convolve the input with the filter kernel
+      for j in 0...i
+        sum += (input[j] * @kernel[kernel_size - (1 + i - j)])
+      end
+      output[i] = sum
+    end
+    
+    for i in kernel_size...input.size
+      sum = 0.0
+      # convolve the input with the filter kernel
+      for j in 0...kernel_size
+        sum += (input[i-j] * @kernel[j])
+      end
+      output[i] = sum
+    end
+    
+    return output
+  end
+  
+  # Calculate the filter frequency magnitude response.
+  # @param [Numeric] use_db Calculate magnitude in dB.
+  def freq_response use_db = false
+
+    input = [0.0] + @kernel # make the size even
+    output = FFT.forward input
+    
+    output = output[0...(output.size / 2)]  # ignore second half (mirror image)
+    output = output.map {|x| x.magnitude }  # calculate magnitudes from complex values
+    
+    if use_db
+      output = output.map {|x| Gain::linear_to_db x }
+    end
+    
+    response = {}
+    output.each_index do |n|
+      frequency = (@sample_rate * n) / (output.size * 2)
+      response[frequency] = output[n]
+    end
+    
+    ## amplitude = 2 * f[j] / size
+    #output = output.map {|x| 2 * x / output.size }
+    
+    return response
+  end
+
+  # Calculate the filter frequency magnitude response and
+  # graph the results.
+  # @param [Numeric] use_db Calculate magnitude in dB.  
+  def plot_freq_response use_db = true
+    plotter = Plotter.new(
+      :title => "Freq magnitude response of #{@order}-order FIR filter",
+      :xlabel => "frequency (Hz)",
+      :ylabel => "magnitude#{use_db ? " (dB)" : ""}",
+      :logscale => "x"
+    )
+    
+    plotter.plot_2d "" => freq_response(use_db)
+  end
+end
+end

data/lib/spcore/filters/fir/sinc_filter.rb

@@ -0,0 +1,68 @@
+require 'pry'
+module SPCore
+
+# Base windowed sinc filter. Implements lowpass and highpass. A bandpass
+# and bandstop filter would be implemented using two of these.
+#
+# Theoretical source: http://www.labbookpages.co.uk/audio/firWindowing.html
+#
+# @author James Tunnell
+#
+class SincFilter
+  include Hashmake::HashMakeable
+
+  # Use to process hashed args in #initialize.  
+  ARG_SPECS = [
+    Hashmake::ArgSpec.new(:key => :order, :reqd => true, :type => Fixnum, :validator => ->(a){ a % 2 == 0 } ),
+    Hashmake::ArgSpec.new(:key => :sample_rate, :reqd => true, :type => Numeric, :validator => ->(a){ a > 0.0 } ),
+    Hashmake::ArgSpec.new(:key => :cutoff_freq, :reqd => true, :type => Numeric, :validator => ->(a){ a > 0.0 } ),
+    Hashmake::ArgSpec.new(:key => :window_class, :reqd => false, :type => Class, :default => BlackmanWindow ),
+  ]
+  
+  attr_reader :lowpass_fir, :highpass_fir
+  
+  # Given a filter order, cutoff frequency, sample rate, and window class,
+  # develop a FIR filter kernel that can be used for lowpass filtering.
+  def initialize args
+    hash_make SincFilter::ARG_SPECS, args
+    
+    raise ArgumentError, "cutoff_freq is greater than 0.5 * sample_rate" if @cutoff_freq > (@sample_rate / 2)
+    
+    size = @order + 1
+    transition_freq = @cutoff_freq / @sample_rate
+    b = TWO_PI * transition_freq
+    
+    # make FIR filter kernels for lowpass and highpass
+    
+    lowpass_kernel = Array.new(size)
+    highpass_kernel = Array.new(size)
+    window = @window_class.new(size)
+    
+    for n in 0...(@order / 2)
+      c = n - (@order / 2)
+      y = Math::sin(b * c) / (Math::PI * (c))
+      lowpass_kernel[size - 1 - n] = lowpass_kernel[n] = y * window.data[n]
+      highpass_kernel[size - 1 - n] = highpass_kernel[n] = -lowpass_kernel[n]
+    end
+    lowpass_kernel[@order / 2] = 2 * transition_freq * window.data[@order / 2]
+    highpass_kernel[@order / 2] = (1 - 2 * transition_freq) * window.data[@order / 2]
+    
+    @lowpass_fir = FIR.new lowpass_kernel, @sample_rate
+    @highpass_fir = FIR.new highpass_kernel, @sample_rate
+  end
+  
+  # Process the input with the lowpass FIR.
+  # @return [Array] containing the filtered input.
+  def lowpass input
+    return @lowpass_fir.convolve input
+  end
+  
+  # Process the input with the highpass FIR.
+  # @return [Array] containing the filtered input.
+  def highpass input
+    return @highpass_fir.convolve input
+  end
+end
+
+
+end

data/lib/spcore/{lib → filters/iir}/biquad_filter.rb

@@ -13,6 +13,8 @@ class BiquadFilter
   # this holds the data required to update samples thru a filter
   Struct.new("BiquadState", :b0, :b1, :b2, :a0, :a1, :a2, :x1, :x2, :y1, :y2)
 
+  # A new instance of BiquadFilter.
+  # @param [Numeric] sample_rate The sample rate to use in calculating coefficients.
   def initialize sample_rate
     @sample_rate = sample_rate
     @biquad = Struct::BiquadState.new(0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0)
@@ -20,14 +22,17 @@ class BiquadFilter
     @bandwidth = 0.0
   end
 
+  # Set the filter critical frequency and bandwidth. 
   def set_critical_freq_and_bw critical_freq, bandwidth
     raise NotImplementedError, "set_critical_freq_and_bW should be implemented in the derived class!"
   end
   
+  # Set the filter critical frequency. 
   def critical_freq= critical_freq
     set_critical_freq_and_bw(critical_freq, @bandwidth);
   end
 
+  # Set the filter bandwidth. 
   def bandwidth= bandwidth
     set_critical_freq_and_bw(@critical_freq, bandwidth);
   end
@@ -56,6 +61,8 @@ class BiquadFilter
     return result
   end
 
+  # Calculate the frequency magnitude response for the given frequency.
+  # @param [Numeric] test_freq The frequency to calculate magnitude response at.
   def get_freq_magnitude_response test_freq
     # Method for determining freq magnitude response is from:
     # http://rs-met.com/documents/dsp/BasicDigitalFilters.pdf

data/lib/spcore/{lib → filters/iir}/cookbook_allpass_filter.rb

@@ -1,4 +1,6 @@
 module SPCore
+# Implement a "cookbook" allpass filter using the BiquadFilter class,
+# based on the well-known RBJ biquad filter.
 class CookbookAllpassFilter < BiquadFilter
   def initialize sample_rate
     super(sample_rate)

data/lib/spcore/{lib → filters/iir}/cookbook_bandpass_filter.rb

@@ -1,4 +1,6 @@
 module SPCore
+# Implement a "cookbook" bandpass filter using the BiquadFilter class,
+# based on the well-known RBJ biquad filter.
 class CookbookBandpassFilter < BiquadFilter
   def initialize sample_rate
     super(sample_rate)

data/lib/spcore/{lib → filters/iir}/cookbook_highpass_filter.rb

@@ -1,4 +1,6 @@
 module SPCore
+# Implement a "cookbook" highpass filter using the BiquadFilter class,
+# based on the well-known RBJ biquad filter.
 class CookbookHighpassFilter < BiquadFilter
   def initialize sample_rate
     super(sample_rate)

data/lib/spcore/{lib → filters/iir}/cookbook_lowpass_filter.rb

@@ -1,4 +1,6 @@
 module SPCore
+# Implement a "cookbook" lowpass filter using the BiquadFilter class,
+# based on the well-known RBJ biquad filter.
 class CookbookLowpassFilter < BiquadFilter
   def initialize sample_rate
     super(sample_rate)

data/lib/spcore/{lib → filters/iir}/cookbook_notch_filter.rb

@@ -1,4 +1,6 @@
 module SPCore
+# Implement a "cookbook" notch (bandstop) filter using the BiquadFilter class,
+# based on the well-known RBJ biquad filter.
 class CookbookNotchFilter < BiquadFilter
   def initialize sample_rate
     super(sample_rate)

data/lib/spcore/interpolation/interpolation.rb

@@ -0,0 +1,64 @@
+module SPCore
+  # Provide interpolation methods, including linear and polynomial.
+class Interpolation
+  # Linear Interpolation Equation:
+  #
+  #        (x3 - x1)(y2 - y1)
+  #  y3 =  ------------------  + y1
+  #            (x2 - x1)
+  #
+  def self.linear x1, y1, x2, y2, x3
+    y3 = ((x3 - x1) * (y2 - y1)) / (x2 - x1);
+    y3 += y1;
+    return y3;
+  end
+
+  # Linear interpolator
+  # Given 2 sample points, interpolates a value anywhere between the two points.
+  #
+  # @param [Numeric] y0 First (left) y-value
+  # @param [Numeric] y0 Second (right) y-value
+  # @param [Numeric] x Percent distance (along the x-axis) between the two y-values
+  def self.linear y0, y1, x
+    raise ArgumentError, "x is not between 0.0 and 1.0" unless x.between?(0.0,1.0)
+    return y0 + x * (y1 - y0)
+  end
+  
+  # 4-point, 3rd-order (cubic) Hermite interpolater (x-form).
+  #
+  # Given 4 evenly-spaced sample points, interpolate a value anywhere between
+  # the middle two points.
+  #
+  # implementation source: www.musicdsp.org/archive.php?classid=5#93
+  #
+  # @param [Float] y0 First y-value
+  # @param [Float] y1 Second y-value (first middle point)
+  # @param [Float] y2 Third y-value (second middle point)
+  # @param [Float] y3 Fourth y-value
+  # @param [Float] x Percent distance (along the x-axis) between the middle two y-values (y1 and y2)
+  def self.cubic_hermite y0, y1, y2, y3, x
+    raise ArgumentError, "x is not between 0.0 and 1.0" unless x.between?(0.0,1.0)
+
+    ## method 1 (slowest)
+    #c0 = y1
+    #c1 = 0.5 * (y2 - y0)
+    #c2 = y0 - 2.5 * y1 + 2*y2 - 0.5 * y3
+    #c3 = 1.5 * (y1 - y2) + 0.5 * (y3 - y0)
+    
+    # method 2 (basically tied with method 3)
+    c0 = y1
+    c1 = 0.5 * (y2 - y0)
+    c3 = 1.5 * (y1 - y2) + 0.5 * (y3 - y0)
+    c2 = y0 - y1 + c1 - c3
+
+    ## method 3 (basically tied with method 2)
+    #c0 = y1
+    #c1 = 0.5 * (y2 - y0)
+    #y0my1 = y0 - y1
+    #c3 = (y1 - y2) + 0.5 * (y3 - y0my1 - y2)
+    #c2 = y0my1 + c1 - c3
+    
+    return ((c3 * x + c2) * x + c1) * x + c0
+  end
+end
+end

data/lib/spcore/resampling/discrete_resampling.rb

@@ -0,0 +1,78 @@
+module SPCore
+# Provide resampling methods (upsampling and downsampling) using
+# discrete filtering.
+class DiscreteResampling
+  
+  def self.upsample input, sample_rate, upsample_factor, filter_order
+    raise ArgumentError, "input.size is less than four" unless input.size >= 4
+    raise ArgumentError, "upsample_factor is not a Fixnum" unless upsample_factor.is_a?(Fixnum)
+    raise ArgumentError, "upsample_factor is not greater than 1" unless upsample_factor > 1
+    raise ArgumentError, "sample_rate is not greater than 0" unless sample_rate > 0
+    
+    output = Array.new((upsample_factor * input.size).to_i, 0.0)
+    input.each_index do |i|
+      output[i * upsample_factor] = input[i] * upsample_factor
+    end
+    
+    filter = SincFilter.new(
+      :sample_rate => (sample_rate * upsample_factor),
+      :order => filter_order,
+      :cutoff_freq => (sample_rate / 2),
+      :window_class => NuttallWindow
+    )
+    
+    return filter.lowpass(output)
+  end
+
+  def self.downsample input, sample_rate, downsample_factor, filter_order
+    raise ArgumentError, "input.size is less than four" unless input.size >= 4
+    raise ArgumentError, "downsample_factor is not a Fixnum" unless downsample_factor.is_a?(Fixnum)
+    raise ArgumentError, "downsample_factor is not greater than 1" unless downsample_factor > 1
+    raise ArgumentError, "sample_rate is not greater than 0" unless sample_rate > 0
+    
+    needed_samples = input.size % downsample_factor
+    if needed_samples == 0
+      input += Array.new(needed_samples, 0.0)
+    end
+
+    filter = SincFilter.new(
+      :sample_rate => sample_rate, :order => filter_order,
+      :cutoff_freq => ((sample_rate / downsample_factor) / 2.0),
+      :window_class => NuttallWindow
+    )
+    
+    filtered = filter.lowpass(input)
+    return Array.new(filtered.size / downsample_factor) { |i| filtered[i * downsample_factor] }
+  end
+  
+  def self.resample input, sample_rate, upsample_factor, downsample_factor, filter_order
+    raise ArgumentError, "input.size is less than four" unless input.size >= 4
+    raise ArgumentError, "upsample_factor is not a Fixnum" unless upsample_factor.is_a?(Fixnum)
+    raise ArgumentError, "upsample_factor is not greater than 1" unless upsample_factor > 1
+    raise ArgumentError, "downsample_factor is not a Fixnum" unless downsample_factor.is_a?(Fixnum)
+    raise ArgumentError, "downsample_factor is not greater than 1" unless downsample_factor > 1
+    raise ArgumentError, "sample_rate is not greater than 0" unless sample_rate > 0
+    
+    upsampled = Array.new((upsample_factor * input.size).to_i, 0.0)
+    input.each_index do |i|
+      upsampled[i * upsample_factor] = input[i] * upsample_factor
+    end
+
+    needed_samples = upsampled.size % downsample_factor
+    if needed_samples == 0
+      upsampled += Array.new(needed_samples, 0.0)
+    end
+    
+    target_rate = sample_rate * upsample_factor / downsample_factor
+    cutoff = (target_rate < sample_rate) ? (target_rate / 2.0) : (sample_rate / 2.0)
+    
+    filter = SincFilter.new(
+      :sample_rate => (sample_rate * upsample_factor), :order => filter_order,
+      :cutoff_freq => cutoff, :window_class => NuttallWindow
+    )
+    filtered = filter.lowpass(upsampled)
+    return Array.new(filtered.size / downsample_factor){ |i| filtered[i * downsample_factor] }
+  end
+
+end
+end