interpolate 0.2.4 → 0.3.0

data/examples/arrays.rb

@@ -15,9 +15,9 @@ time_frames = {
   6 => [0, 0, 0]
 }
 
-path = Interpolation.new(time_frames)
+path = Interpolate::Points.new(time_frames)
 
-# play the actors positions in time increments of 0.25
+# play the actor's positions in time increments of 0.25
 (0).step(6, 0.25) do |time|
   position = path.at(time)
   puts ">> At #{time}s, actor is at:"

data/examples/buckets.rb

@@ -4,16 +4,14 @@ require 'interpolate'
 # min_value => bucket
 buckets = {
   0.000 => 1,
-  0.427 => 2,
-  1.200 => 3,
-  3.420 => 4,
-  27.50 => 5,
-  45.20 => 6,
-  124.4 => 7,
+  0.500 => 2,
+  1.250 => 3,
+  7.725 => 4,
+  28.85 => 5,
+  50.00 => 6,
+  127.5 => 7
 }
 
-bucketizer = Interpolation.new(buckets)
-
 values = [
   -20.2,
   0.234,
@@ -23,6 +21,11 @@ values = [
   4000
 ]
 
+# using Interpolate::Points to place values within discrete intervals
+bucketizer = Interpolate::Points.new(buckets)
+# the blending function will mimic the mathematical floor function
+bucketizer.blend_with {|low, high, balance| low }
+
 values.each do |value|
   bucket = bucketizer.at(value).floor
   puts "A value of #{value} falls into bucket #{bucket}"

data/examples/colors.rb

@@ -1,33 +1,35 @@
 require 'rubygems'
-require 'color'
 require 'interpolate'
-
-# we need to implement +interpolate+ for Color::RGB
-# in order for Interpolation to work
-class Color::RGB
-  def interpolate(other, balance)
-    mix_with(other, balance * 100.0)
-  end
-end
+require 'color'
 
 # a nice weathermap-style color gradient
 points = {
-  1 => Color::RGB::White,
+  1 => Color::RGB::Cyan,
   2 => Color::RGB::Lime,
 # 3 => ? (between Lime and Yellow; Interpolate will figure it out)
   4 => Color::RGB::Yellow,
   5 => Color::RGB::Orange,
   6 => Color::RGB::Red,
-  7 => Color::RGB::Magenta
+  7 => Color::RGB::Magenta,
+  8 => Color::RGB::White,
 }
 
-gradient = Interpolation.new(points)
+# we need to implement a blending function in order for Interpolate::Points to
+# work properly
+#
+# fortunately, Color::RGB includes +mix_with+, which is almost functionally
+# identical to what we need
+
+gradient = Interpolate::Points.new(points)
+gradient.blend_with {|color, other, balance|
+  color.mix_with(other, balance * 100.0)
+}
 
-# what are the colors of the gradient from 1 to 7
+# what are the colors of the gradient from 1 to 8
 # in increments of 0.2?
 (1).step(7, 0.2) do |value|
   color = gradient.at(value)
-  puts "A value of #{value} means #{color.html}"
+  puts "A value of #{value.round(3)} means #{color.html}"
 end
 
 

data/examples/nested.rb

@@ -14,7 +14,7 @@ time_frames = {
 }
 
 
-paths = Interpolation.new(time_frames)
+paths = Interpolate::Points.new(time_frames)
 
 # show the vertex positions in time increments of 0.25
 (0).step(4, 0.25) do |time|

data/interpolate.gemspec

@@ -1,65 +1,30 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
+$LOAD_PATH.unshift File.expand_path('../lib/', __FILE__)
+require 'interpolate/version'
 
-Gem::Specification.new do |s|
-  s.name = %q{interpolate}
-  s.version = "0.2.4"
+Gem::Specification.new do |gem|
+  gem.required_rubygems_version = '>= 1.3.6'
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Adam Collins"]
-  s.date = %q{2011-04-10}
-  s.description = %q{Description
+  # Gem metadata
+  gem.name        = 'interpolate'
+  gem.version     = Interpolate::VERSION
+  gem.platform    = Gem::Platform::RUBY
 
-Library for generic Interpolation objects. Useful for such things as generating
-linear motion between points (or arrays of points), multi-channel color
-gradients, piecewise functions, or even just placing values within intervals.
-}
-  s.email = %q{adam@m104.us}
-  s.extra_rdoc_files = [
-    "LICENSE",
-    "README.md"
-  ]
-  s.files = [
-    "CHANGELOG.md",
-    "LICENSE",
-    "Manifest.txt",
-    "README.md",
-    "Rakefile",
-    "VERSION",
-    "examples/arrays.rb",
-    "examples/buckets.rb",
-    "examples/colors.rb",
-    "examples/nested.rb",
-    "interpolate.gemspec",
-    "lib/interpolate.rb",
-    "lib/interpolate/add/core.rb",
-    "lib/interpolate/add/core/array.rb",
-    "lib/interpolate/add/core/numeric.rb",
-    "lib/interpolate/interpolation.rb",
-    "test/test_all.rb"
-  ]
-  s.homepage = %q{http://github.com/m104/interpolate}
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
-  s.summary = %q{Create linear interpolations from key points and values}
-  s.test_files = [
-    "examples/arrays.rb",
-    "examples/buckets.rb",
-    "examples/colors.rb",
-    "examples/nested.rb",
-    "test/test_all.rb"
-  ]
+  gem.summary     = 'Create arbitrary interpolations from key points and values'
+  gem.description = 'Interpolate is a library for generic linear interpolation objects. Useful for such things as calculating linear motion between locations (or arrays of locations), multi-channel color gradients, piecewise functions, or even just placing values within intervals.'
 
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
+  gem.authors     = ['Adam Collins']
+  gem.email       = ['adam@m104.us']
+  gem.homepage    = 'http://github.com/m104/interpolate'
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-    else
-    end
-  else
-  end
+  # Dependencies
+  gem.require_paths = ['lib']
+  #gem.add_development_dependency "rspec"
+  #gem.add_runtime_dependency "whatever"
+
+  # Manifest
+  all_files      = `git ls-files`.split("\n")
+  gem.files      = all_files
+  gem.test_files = all_files.grep(/^test\//)
 end
 

data/lib/interpolate.rb

@@ -1,2 +1,15 @@
-require 'interpolate/interpolation'
+require 'interpolate/base'
 require 'interpolate/add/core'
+
+# deprecated as of 0.3.0; use Interpolate::Points instead
+class Interpolation
+  class << self
+    # metaclass :new override method to return an instance of
+    # Interpolate::Points
+    def new(*args)
+      warn "::Interpolation has been deprecated as of 0.3.0; use Interpolate::Points"
+      Interpolate::Points.new(*args)
+    end
+  end
+end
+

data/lib/interpolate/add/core/array.rb

@@ -24,17 +24,17 @@ class Array
   #
   # This method is intentionally abstract to allow for the interpolation
   # of nested arrays.  In this case, both arrays need to have the same array
-  # structure (same number of dimensions, equal length in each dimension), 
+  # structure (same number of dimensions, equal length in each dimension),
   # but the contents can, of course, be different.
   #
-  # A balance greater than or equal to 0.0 returns +self+, while a
-  # balance less than or equal to 1.0 returns +other+.
+  # A balance less than or equal to 0.0 returns +self+, while a
+  # balance greater than or equal to 1.0 returns +other+.
   def interpolate(other, balance)
     if (self.length < 1) then
-      raise ArgumentError, "cannot interpolate array with no values"
+      raise ArgumentError, "cannot interpolate empty array"
     end
 
-    if (self.length != other.length) then
+    if self.length != other.length then
       raise ArgumentError, "cannot interpolate between arrays of different length"
     end
 
@@ -44,16 +44,14 @@ class Array
 
     final = Array.new
 
-    self.each_with_index do |left, index|
-      unless (left.respond_to? :interpolate) then
+    self.each_with_index do |value, index|
+      unless value.respond_to? :interpolate then
         raise "array element does not respond to :interpolate"
       end
 
-      right = other[index]
-
-      final[index] = left.interpolate(right, balance)
+      final[index] = value.interpolate(other[index], balance)
     end
 
-    return final
+    final
   end
 end

data/lib/interpolate/add/core/numeric.rb

@@ -16,17 +16,18 @@ class Numeric
   # +self+ and +other+.  +balance+ should be a Float from 0.0 to 1.0,
   # where the value is a ratio between +self+ and +other+.
   #
-  # A balance greater than or equal to 0.0 returns +self+, while a
-  # balance less than or equal to 1.0 returns +other+.
+  # A balance less than or equal to 0.0 returns +self+, while a
+  # balance greater than or equal to 1.0 returns +other+.
   def interpolate(other, balance)
+    # everything should be a Float
     balance = balance.to_f
     left = self.to_f
     right = other.to_f
-    
+
     # catch the easy cases
     return left if (balance <= 0.0)
     return right if (balance >= 1.0)
-    
+
     delta = (right - left).to_f
     return left + (delta * balance)
   end

data/lib/interpolate/base.rb

@@ -0,0 +1,179 @@
+# Interpolate is a library for generic linear interpolation objects. Useful for
+# such things as calculating linear motion between locations (or arrays of
+# locations), multi-channel color gradients, piecewise functions, or even just
+# placing values within intervals.
+#
+# Interpolation generators can be created with the Interpolate::Points class,
+# given a set of interpolation "key points" and associated key values. By
+# default, the key values should be able to calculate their own blending
+# function (by defining an +interpolate+ instance method). Alternatively, the
+# Interpolate::Points object can be passed a block that takes three arguments:
+# the lower value, the higher value, and the balance ratio between the two.
+#
+# For the balance ratio, 0.0 means 100% of the lower value and a balance ratio
+# of 1.0 means 100% of the higher value. A balance ratio of 0.5 means that the
+# Interpolate::Points object has determined that the interpolated value should
+# be a 50%/50% mixture of the lower and higher values.  It is up to the blending
+# function to determine how to calculate the interpolated value.
+#
+# A Interpolate::Points objects is constructed with a Hash object, wherein each
+# key is a Numeric and each value is an object (which itself may respond to
+# +interpolate+). If any of the value objects do not respond to +interpolate+, a
+# blending function (+blend_with+) must be used to determine the interpolated
+# values.
+#
+# The default blending function, Interpolate::Points::DEFAULT_BLEND, simply
+# calls the +interpolate+ method on the lower key value with the arguments of 1)
+# the higher key value and 2) the balance ratio.
+#
+#
+# ==Author
+#
+# {Adam Collins}[mailto:adam@m104.us]
+#
+#
+# ==License
+#
+# Licensed under the MIT license.
+#
+
+module Interpolate
+
+  class Points
+    attr_reader :points
+
+    # default blending function, which delegates to the :interpolate method on
+    # each given value object
+    DEFAULT_BLEND = lambda { |value, other, balance|
+      unless value.respond_to? :interpolate
+        raise "found an object (#{value.inspect}) that doesn't respond to :interpolate"
+      end
+      value.interpolate(other, balance)
+    }
+
+    # creates an Interpolate::Points object with an optional Hash object that
+    # specifies key points (Numeric) and associated value objects
+    #
+    # the blend_with Proc can also be given when creating a new
+    # Interpolate::Points object
+    def initialize(points = {}, &block)
+      @points = {}
+      @blend_with = block
+      merge!(points)
+    end
+
+    # define the blending function to use with this Interpolate::Points object
+    #
+    # setting this to +nil+ will reset the blending behavior back to calling
+    # the default blending function
+    def blend_with(&block)
+      @blend_with = block
+    end
+
+    # returns a new Interpolate::Points object with the given key points merged
+    # with the original points
+    def merge(points = {})
+      Points.new(points.merge(@points))
+    end
+
+    # merges the given key points with the original points
+    def merge!(points = {})
+      # points must be a Hash
+      raise ArgumentError, "key points must be a Hash object" unless points.is_a? Hash
+      # ensure the points are all keyed Numeric-ally
+      points.each do |key, value|
+        raise ArgumentError, "found a point key that is not a Numeric object: #{key.inspect}" unless key.is_a? Numeric
+      end
+
+      @points.merge!(points)
+      normalize_data
+      self
+    end
+
+    # returns the interpolated value at the Numeric point specified, optionally
+    # using a given block as the blending function
+    #
+    # if no key points have been specified, the return value is +nil+
+    #
+    # if one key point has been specified, the return value is the value
+    # of that key point
+    #
+    # if the given point falls outside the interpolation key range (lower than
+    # the lowest key point or higher than the highest key point), the nearest
+    # point value is used; in other words, no extrapolation is performed
+    #
+    # otherwise, the interpolated value is calculated in accordance with the
+    # first of:
+    #
+    #   * the given block
+    #   * the stored blending function, :blend_with
+    #   * a call to :interpolate on a key value object
+    #
+    def at(point, &block)
+      # obvious cases first
+      if @sorted.empty?
+        # no key points
+        return nil
+      elsif @sorted.size == 1
+        # one key point
+        return @sorted.first.last
+      end
+
+      # out-of-bounds cases next
+      if point <= @min_point
+        # lower than lowest key point
+        return @sorted.first.last
+      elsif point >= @max_point
+        # higher than highest key point
+        return @sorted.last.last
+      end
+
+      # binary search to find the right interpolation key point/value interval
+      left = 0
+      right = @sorted.length - 2 # highest point will be included
+      low_point = nil
+      low_value = nil
+      high_point = nil
+      high_value = nil
+
+      while left <= right
+        middle = (right - left) / 2 + left
+
+        (low_point, low_value) = @sorted[middle]
+        (high_point, high_value) = @sorted[middle + 1]
+
+        break if low_point <= point and point <= high_point
+
+        if point < low_point
+          right = middle - 1
+        else
+          left = middle + 1
+        end
+      end
+
+      # determine the balance ratio
+      span = high_point - low_point
+      balance = (point.to_f - low_point) / span
+
+      # choose and call the blending function
+      blend = block || @blend_with || DEFAULT_BLEND
+      blend.call(low_value, high_value, balance)
+    end
+
+    alias :[] :at
+
+    private
+
+    def normalize_data # :nodoc:
+      @sorted = @points.sort
+      unless @sorted.empty?
+        @min_point = @sorted.first.first
+        @max_point = @sorted.last.first
+      end
+    end
+
+  end # class Points
+
+end # module Interpolate
+
+