spcore 0.1.2 → 0.1.3

data/lib/spcore/resampling/hybrid_resampling.rb

@@ -0,0 +1,30 @@
+module SPCore
+# Provide resampling method using polynomial upsampling and discrete filtering
+# for downsampling.
+class HybridResampling
+  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 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 = PolynomialResampling.upsample input, sample_rate, upsample_factor
+    
+    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

data/lib/spcore/resampling/polynomial_resampling.rb

@@ -0,0 +1,56 @@
+module SPCore
+# Provide resampling methods (upsampling and downsampling) using
+# polynomial interpolation.
+class PolynomialResampling
+  
+  def self.upsample input, sample_rate, upsample_factor
+    raise ArgumentError, "input.size is less than four" unless input.size >= 4
+    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)
+    
+    input_size_f = input.size.to_f
+    input_size_minus_1 = input.size - 1
+    input_size_minus_2 = input.size - 2
+    output_size_f = output.size.to_f
+    output.each_index do |i|
+      
+      i_f = i.to_f
+      index_into_input = (i_f / output_size_f) * input_size_f
+      index_into_input_i = index_into_input.to_i
+      
+      if(index_into_input <= 1.0) # before second sample
+        point1 = input[0]
+        point2 = input[0]
+        point3 = input[1]
+        point4 = input[2]
+        x = index_into_input
+        output[i] = Interpolation.cubic_hermite(point1, point2, point3, point4, x)
+      elsif(index_into_input >= input_size_minus_1) # past last sample
+        point1 = input[input_size_minus_1 - 1]
+        point2 = input[input_size_minus_1]
+        point3 = input[input_size_minus_1]
+        point4 = input[input_size_minus_1]
+        x = index_into_input - index_into_input.floor
+        output[i] = Interpolation.cubic_hermite(point1, point2, point3, point4, x)
+      elsif(index_into_input >= input_size_minus_2)  # past second-to-last sample
+        point1 = input[index_into_input_i - 1]
+        point2 = input[index_into_input_i]
+        point3 = input[input_size_minus_1]
+        point4 = input[input_size_minus_1]
+        x = index_into_input - index_into_input.floor
+        output[i] = Interpolation.cubic_hermite(point1, point2, point3, point4, x)
+      else # general case
+        point1 = input[index_into_input_i - 1]
+        point2 = input[index_into_input_i]
+        point3 = input[index_into_input_i + 1]
+        point4 = input[index_into_input_i + 2]
+        x = index_into_input - index_into_input.floor
+        output[i] = Interpolation.cubic_hermite(point1, point2, point3, point4, x)
+      end
+    end
+  end
+  
+end
+end

data/lib/spcore/transforms/dft.rb

@@ -0,0 +1,47 @@
+module SPCore
+# Perform DFT transforms, forward and inverse.
+# @author James Tunnell
+class DFT
+  # @param [Array] input  array of real values, representing the time domain
+  #                       signal to be passed into the forward DFT.
+  def self.forward input
+    input_size = input.size
+    raise ArgumentError, "input.size is not even" unless (input_size % 2 == 0)
+    
+    output_size = input_size
+    output = Array.new(output_size)
+    
+    output.each_index do |k|
+      sum = Complex(0.0)
+      input.each_index do |n|
+        a = TWO_PI * n * k / input_size
+        sum += Complex(input[n] * Math::cos(a), -input[n] * Math::sin(a))
+      end
+      output[k] = sum
+    end
+    
+    return output
+  end
+  
+  # @param [Array] input  array of complex values, representing the frequency domain
+  #                       signal obtained from the forward DFT.
+  def self.inverse input
+    input_size = input.size
+    raise ArgumentError, "input.size is not even" unless (input_size % 2 == 0)
+    
+    output = Array.new(input_size)
+    output_size = output.size
+    
+    output.each_index do |k|
+      sum = Complex(0.0)
+      input.each_index do |n|
+        a = TWO_PI * n * k / input_size
+        sum += Complex(input[n] * Math::cos(a), input[n] * Math::sin(a))
+      end
+      output[k] = sum / output_size
+    end
+    
+    return output    
+  end
+end
+end

data/lib/spcore/transforms/fft.rb

@@ -0,0 +1,125 @@
+module SPCore
+# Perform FFT transforms, forward and inverse.
+# @author James Tunnell
+class FFT
+
+  # Forward Radix-2 FFT transform using decimation-in-time. Operates on an array
+  # of real values, representing a time domain signal.
+  # Ported from unlicensed MATLAB code which was posted to the MathWorks file
+  # exchange by Dinesh Dileep Gaurav.
+  # See http://www.mathworks.com/matlabcentral/fileexchange/17778.
+  # @param [Array] input An array of numeric values. If size is not an exact
+  #                      radix-2 number, then zeros will be appended until it is,
+  #                      unless force_radix_2_size is set false.
+  # @param force_radix_2_size If true, any input that does not have an exact
+  #                           power-of-two size will be appended with zeros
+  #                           until it does. Set true by default.
+  # @raise [ArgumentError] if input size is not an exact radix-2 number and
+  #                        force_radix_2_size is false.
+  def self.forward input, force_radix_2_size = true
+    size = input.size
+    power_of_two = Math::log2(size)
+    if power_of_two.floor != power_of_two # input size is not an even power of two
+      if force_radix_2_size
+        new_size = 2**(power_of_two.to_i() + 1)
+        input += Array.new(new_size - size, 0.0)
+        
+        size = input.size
+        power_of_two = Math::log2(size)
+      else
+        raise ArgumentError, "input.size #{size} is not a radix-2 number"
+      end
+    end
+    power_of_two = power_of_two.to_i
+    x = bit_reverse_order input, power_of_two
+    
+    phase = Array.new(size/2){|n|
+      Complex(Math::cos(TWO_PI*n/size), -Math::sin(TWO_PI*n/size))
+    }
+    for a in 1..power_of_two
+      l = 2**a
+      phase_level = []
+
+      0.step(size/2, size/l) do |i|
+        phase_level << phase[i]
+      end
+      
+      ks = []
+      0.step(size-l, l) do |k|
+        ks << k
+      end
+
+      ks.each do |k|
+        for n in 0...l/2
+          idx1 = n+k
+          idx2 = n+k + (l/2)
+          
+          first  = x[idx1]
+          second = x[idx2] * phase_level[n]
+          x[idx1] = first + second
+          x[idx2] = first - second
+        end
+      end
+    end
+    return x
+  end
+
+  # Inverse Radix-2 FFT transform. Operates on an array of complex values, as
+  # one would obtain from the forward FFT transform.
+  # Ported from unlicensed MATLAB code which was posted to the MathWorks file
+  # exchange by Dinesh Dileep Gaurav.
+  # See http://www.mathworks.com/matlabcentral/fileexchange/17778.
+  # @param [Array] input An array of complex values. Must have a radix-2 size
+  #                         (2, 4, 8, 16, 32, ...).
+  # @raise [ArgumentError] if input size is not an exact power-of-two.
+  def self.inverse input
+    size = input.size
+    power_of_two = Math::log2(size)
+    raise ArgumentError, "input.size #{size} is not power of 2" if power_of_two.floor != power_of_two
+    power_of_two = power_of_two.to_i
+    x = bit_reverse_order input, power_of_two
+    
+    phase = Array.new(size/2){|n|
+      Complex(Math::cos(TWO_PI*n/size), -Math::sin(TWO_PI*n/size))
+    }
+    for a in 1..power_of_two
+      l = 2**a
+      phase_level = []
+
+      0.step(size/2, size/l) do |i|
+        phase_level << phase[i]
+      end
+      
+      ks = []
+      0.step(size-l, l) do |k|
+        ks << k
+      end
+
+      ks.each do |k|
+        for n in 0...l/2
+          idx1 = n+k
+          idx2 = n+k + (l/2)
+          
+          first  = x[idx1]
+          second = x[idx2] * phase_level[n]
+          x[idx1] = (first + second)
+          x[idx2] = (first - second)
+        end
+      end
+    end
+    
+    return x.map {|val| val / size }
+  end
+
+  private
+
+  def self.get_bit_reversed_addr i, nbits
+    i.to_s(2).rjust(nbits, '0').reverse!.to_i(2)
+  end
+  
+  def self.bit_reverse_order input, m
+    Array.new(input.size){|i| input[get_bit_reversed_addr(i, m)] }
+  end
+
+end
+end

data/lib/spcore/{lib → util}/gain.rb

@@ -1,4 +1,5 @@
 module SPCore
+# Provide utility functions to convert between a linear and decibel (logarithm) unit.
 class Gain
   
   #MAX_DB = 72
@@ -167,12 +168,14 @@ class Gain
 
   MAX_DB_ABS = 6000.0
 
+  # Convert a decibel value to a linear value.
   def self.db_to_linear db
     db_abs = db.abs
     raise ArgumentError, "|db| is #{db_abs}, which is greater than the allowed #{MAX_DB_ABS}" if db_abs > MAX_DB_ABS
     return 10.0**(db / 20.0)
   end
   
+  # Convert a linear value to a decibel value.
   def self.linear_to_db linear
     raise ArgumentError, "linear value #{linear} is less than or equal to 0.0" if linear <= 0.0
     return 20.0 * Math::log10(linear)

data/lib/spcore/{core → util}/limiters.rb

@@ -1,11 +1,15 @@
 module SPCore
+# Provides methods to make limiting Proc objects, bound to
+# the given limits.
 class Limiters
+  # make a limiter that actually doesn't limit at all.
   def self.make_no_limiter
     return lambda do |input|
       return input
     end
   end
-    
+  
+  # make a limiter that keeps values within the given range.
   def self.make_range_limiter range
     return lambda do |input|
       if input < range.first
@@ -18,6 +22,7 @@ class Limiters
     end
   end
 
+  # make a limiter that keeps values at or below the given upper limit.
   def self.make_upper_limiter limit
     return lambda do |input|
       if input > limit
@@ -28,6 +33,7 @@ class Limiters
     end
   end
 
+  # make a limiter that keeps values at or above the given lower limit.
   def self.make_lower_limiter limit
     return lambda do |input|
       if input < limit
@@ -38,6 +44,9 @@ class Limiters
     end
   end
   
+  # make a limiter that limits values to a set of good values. Given also the
+  # current value, it either returns the input value if it's included in
+  # the set of good values, or it returns the current value.
   def self.make_enum_limiter good_values
     return lambda do |input, current|
       if good_values.include?(input)

data/lib/spcore/util/plotter.rb

@@ -0,0 +1,91 @@
+require 'gnuplot'
+
+module SPCore
+
+# Helps make plotting data even easier. Uses gnuplot.
+class Plotter
+  include Hashmake::HashMakeable
+  
+  # Used to process hashed args passed to #initialize.
+  ARG_SPECS = [
+    Hashmake::ArgSpec.new(:key => :title, :type => String, :reqd => false, :default => ""),
+    Hashmake::ArgSpec.new(:key => :xlabel, :type => String, :reqd => false, :default => "x"),
+    Hashmake::ArgSpec.new(:key => :ylabel, :type => String, :reqd => false, :default => "y"),
+    Hashmake::ArgSpec.new(:key => :linestyle, :type => String, :reqd => false, :default => "lines"),
+    Hashmake::ArgSpec.new(:key => :linewidth, :type => Fixnum, :reqd => false, :default => 1, :validator => ->(a){ a >= 1 }),
+    Hashmake::ArgSpec.new(:key => :logscale, :type => String, :reqd => false, :default => ""),
+  ]
+  
+  # A new instance of Plotter.
+  # @param [Hash] hashed_args A hash containing initialization parameters.
+  #                           All params are optional. See ARG_SPECS for
+  #                           parameter details.
+  def initialize hashed_args = {}
+    hash_make Plotter::ARG_SPECS, hashed_args
+  end
+  
+  # Plot XY datapoints.
+  # @param [Hash] titled_hashes A hash that maps dataset titles to data. The data itself
+  #                             is a hash also, that maps x values to y values. For example,
+  #                             plot_2d could be called passing it the hash { "somedata" => {0.0 => 4.0, 1.0 => 2.0}}
+  def plot_2d titled_hashes
+    datasets = []
+    titled_hashes.each do |title, hash|
+      dataset = Gnuplot::DataSet.new( [hash.keys, hash.values] ){ |ds|
+        ds.with = @linestyle
+        ds.title = title
+        ds.linewidth = @linewidth
+      }
+      datasets << dataset
+    end
+    
+    plot_datasets datasets
+  end
+
+  # Plot a sequence of values.
+  # @param [Hash] titled_sequences A hash that maps sequence titles to data. The data itself
+  #                             is an array of values. In the plot, values will be mapped to
+  #                             their index in the sequence. For example, plot_1d could be
+  #                             called passing it the hash { "somedataseq" => [0,2,3,6,3,-1]}
+  # @param plot_against_fraction If true, instead of plotting samples against sample number, plot
+  #                              them against the fraction (sample_number / total_samples).
+  def plot_1d titled_sequences, plot_against_fraction = false
+    datasets = []
+    titled_sequences.each do |title, sequence|
+      indices = Array.new(sequence.size)
+      sequence.each_index do |i|
+        indices[i] = i
+        if plot_against_fraction
+          indices[i] /= sequence.size.to_f
+        end
+      end
+      
+      dataset = Gnuplot::DataSet.new( [indices, sequence] ){ |ds|
+        ds.with = @linestyle
+        ds.title = title
+        ds.linewidth = @linewidth
+      }
+      datasets << dataset
+    end
+    
+    plot_datasets datasets
+  end
+
+  # Plot Gnuplot::DataSet objects.
+  # @param [Array] datasets An array of Gnuplot::DataSet objects.
+  def plot_datasets datasets
+    Gnuplot.open do |gp|
+      Gnuplot::Plot.new(gp) do |plot|
+        plot.title  @title
+        plot.xlabel @xlabel
+        plot.ylabel @ylabel
+        plot.data = datasets
+        
+        if @logscale_x
+          plot.logscale "x"
+        end
+      end
+    end
+  end
+end
+end

data/lib/spcore/{lib → util}/saturation.rb

@@ -1,4 +1,5 @@
 module SPCore
+# Provide simple saturation methods, that limit input above the given threshold value.
 class Saturation
   # Sigmoid-based saturation when input is above threshold.
   # From musicdsp.org, posted by Bram.
@@ -18,6 +19,7 @@ class Saturation
     end
   end
   
+  # A Gompertz-sigmoid-based saturation when input is above threshold.
   def self.gompertz input, threshold
     a = threshold
     b = -4
@@ -32,14 +34,5 @@ class Saturation
     end
   end
   
-  private
-  
-  #def self.mock_sigmoid x
-  #  if(x.abs < 1.0)
-  #    return x * (1.5 - 0.5 * x * x)
-  #  else
-  #    return x > 0.0 ? 1.0 : -1.0
-  #  end
-  #end
 end
 end

data/lib/spcore/util/scale.rb

@@ -0,0 +1,41 @@
+module SPCore
+# Provide methods for generating sequences that scale linearly or exponentially.
+class Scale
+  # Produce a sequence of values that progresses in a linear fashion.
+  # @param [Range] range The start and end values the set should include.
+  # @param [Fixnum] n_points The number of points to create for the sequence, including the start and end points.
+  # @raise [ArgumentError] if n_points is < 2.
+  def self.linear range, n_points
+    raise ArgumentError, "n_points is < 2" if n_points < 2
+    incr = (range.last - range.first) / (n_points - 1)
+    points = Array.new(n_points)
+    value = range.first
+    
+    points.each_index do |i|
+      points[i] = value
+      value += incr
+    end
+    
+    return points
+  end
+
+  # Produce a sequence of values that progresses in an exponential fashion.
+  
+  # @param [Range] range The start and end values the set should include.
+  # @param [Fixnum] n_points The number of points to create for the sequence, including the start and end points.
+  # @raise [ArgumentError] if n_points is < 2.  
+  def self.exponential range, n_points
+    raise ArgumentError, "n_points is < 2" if n_points < 2
+    multiplier = (range.last / range.first)**(1.0/(n_points-1))
+    points = Array.new(n_points)
+    value = range.first
+    
+    points.each_index do |i|
+      points[i] = value
+      value *= multiplier
+    end
+    
+    return points
+  end
+end
+end