interpolate 0.2.0

data/CHANGELOG

@@ -0,0 +1,17 @@
+== 0.2.0
+
+* Changed the library name to "interpolate"
+* Added Array#interpolate that covers uniform arrays and nested arrays
+* Added more tests, documentation, and examples
+
+== 0.1.0
+
+* Gadient calls :interpolate on values for OOP goodness
+* Checks added for respond_to? :interpolate on values
+* Added Numeric#interpolate
+
+== 0.0.1
+
+* Initial coding
+* N-sized arbitrary floating point gradients
+

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Adam Collins [adam.w.collins@gmail.com]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,11 @@
+CHANGELOG
+MIT-LICENSE
+Manifest.txt
+README.txt
+Rakefile
+examples/arrays.rb
+examples/colors.rb
+examples/nested.rb
+examples/zones.rb
+lib/interpolate.rb
+test/test_all.rb

data/README.txt

@@ -0,0 +1,11 @@
+== Interpolate
+
+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.
+
+== Author
+
+Adam Collins
+adam.w.collins@gmail.com
+

data/Rakefile

@@ -0,0 +1,21 @@
+require 'rubygems'
+require 'hoe'
+$:.unshift(File.dirname(__FILE__) + "/lib")
+require 'interpolate'
+
+Hoe.new('Interpolate', Interpolation::VERSION) do |p|
+  p.name = "interpolate"
+  p.author = "Adam Collins"
+  p.description = "Library for creating generic interpolations objects."
+  p.email = 'adam.w.collins@gmail.com'
+  p.summary = "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."
+  p.url = "http://interpolate.rubyforge.org"
+  #p.clean_globs = [''] # Remove this directory on "rake clean"
+  p.remote_rdoc_dir = '' # Release to root
+  p.changes = p.paragraphs_of('CHANGELOG', 0..1).join("\n\n")
+  # * extra_deps - An array of rubygem dependencies.
+end
+
+desc "Release and publish documentation"
+task :repubdoc => [:release, :publish_docs]
+

data/examples/arrays.rb

@@ -0,0 +1,26 @@
+require 'rubygems'
+require 'interpolate'
+require 'pp'
+
+
+# a non-linear set of multi-dimensional points;
+# perhaps the location of some actor in relation to time
+time_frames = {
+  0 => [0, 0, 0],
+  1 => [1, 0, 0],
+  2 => [0, 1, 0],
+  3 => [0, 0, 2],
+  4 => [3, 0, 1],
+  5 => [1, 2, 3],
+  6 => [0, 0, 0]
+}
+
+path = Interpolation.new(time_frames)
+
+# play the actors 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:"
+  p position
+end
+

data/examples/colors.rb

@@ -0,0 +1,35 @@
+require 'rubygems'
+require 'interpolate'
+require 'color'
+
+
+# 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
+
+# a nice weathermap-style color gradient
+points = {
+  0 => Color::RGB::White,
+  1 => Color::RGB::Lime,
+# 2 => ? (something between Lime and Yellow)
+  3 => Color::RGB::Yellow,
+  4 => Color::RGB::Orange,
+  5 => Color::RGB::Red,
+  6 => Color::RGB::Magenta,
+  7 => Color::RGB::DarkGray
+}
+
+
+gradient = Interpolation.new(points)
+
+# what are the colors of the gradient from 0 to 7
+# in increments of 0.2?
+(0).step(7, 0.2) do |value|
+  color = gradient.at(value)
+  puts "A value of #{value} means #{color.html}"
+end
+

data/examples/nested.rb

@@ -0,0 +1,26 @@
+require 'rubygems'
+require 'interpolate'
+require 'pp'
+
+
+# a non-linear set of 2D vertexes;
+# the shape changes at each frame
+time_frames = {
+  0 => [[0, 0], [1, 0], [2, 0], [3, 0], [4, 0]], # a horizontal line
+  1 => [[0, 0], [1, 0], [3, 0], [0, 4], [0, 0]], # a triangle
+  2 => [[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]], # a square
+  3 => [[0, 0], [1, 0], [2, 0], [3, 0], [4, 0]], # a horizontal line, again
+  4 => [[0, 0], [0, 1], [0, 2], [0, 3], [0, 4]]  # a vertical line
+}
+
+
+paths = Interpolation.new(time_frames)
+
+# show the vertex positions in time increments of 0.25
+(0).step(4, 0.25) do |time|
+  points = paths.at(time)
+  puts ">> At #{time}s, points are:"
+  p points
+end
+
+

data/examples/zones.rb

@@ -0,0 +1,28 @@
+require 'rubygems'
+require 'interpolate'
+
+points = {
+  0.000 => 0,
+  0.427 => 1,
+  1.200 => 2,
+  3.420 => 3,
+  27.50 => 4,
+  45.20 => 5,
+  124.4 => 6,
+}
+
+zones = Interpolation.new(points)
+
+values = [
+  -20.2,
+  0.234,
+  65.24,
+  9.234,
+  398.4,
+  4000
+]
+
+values.each do |value|
+  zone = zones.at(value).floor
+  puts "A value of #{value} falls into zone #{zone}"
+end

data/lib/interpolate.rb

@@ -0,0 +1,304 @@
+=begin rdoc
+
+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.
+
+The only requirement is that each interpolation point value must be able to
+figure out how to interpolate itself to its neighbor value(s). Numeric
+objects and uniformly sized arrays are automatically endowed with this
+ability by this gem, but other classes will require an implementation
+of #interpolate. See the second example below for a brief demonstration
+using Color objects.
+
+Interpolation objects are constructed with a Hash object, wherein each key
+is a real number value and each value is can respond to #interpolate and
+determine the resulting value based on its neighbor value and the balance
+ratio between the two points.
+
+At or below the lower bounds of the interpolation, the result will be equal to
+the value of the lower bounds interpolation point.  At or above the upper
+bounds of the graient, the result will be equal to the value of the upper
+bounds interpolation point.
+
+
+==Author
+
+{Adam Collins}[mailto:adam.w.collins@gmail.com]
+
+
+==General Usage
+
+Specify the interpolation as a Hash, where keys represent numeric points
+along the gradient and values represent the known values along that gradient.
+
+Here's an example for determining which of 7 zones a set of values fall into:
+
+  require 'rubygems'
+  require 'interpolate'
+
+  points = {
+    0.000 => 0,
+    0.427 => 1,
+    1.200 => 2,
+    3.420 => 3,
+    27.50 => 4,
+    45.20 => 5,
+    124.4 => 6,
+  }
+
+  zones = Interpolation.new(points)
+
+  values = [
+    -20.2,
+    0.234,
+    65.24,
+    9.234,
+    398.4,
+    4000
+  ]
+
+  values.each do |value|
+    zone = zones.at(value).floor
+    puts "A value of #{value} falls into zone #{zone}"
+  end
+
+
+==Non-Numeric Gradients
+
+For non-Numeric gradient value objects, you'll need to implement :interpolate
+for the class in question.  Here's an example using an RGB color gradient with
+the help of the 'color' gem:
+
+  require 'rubygems'
+  require 'interpolate'
+  require 'color'
+
+  # 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
+
+  # a nice weathermap-style color gradient
+  points = {
+    0 => Color::RGB::White,
+    1 => Color::RGB::Lime,
+  # 2 => ? (something between Lime and Yellow)
+    3 => Color::RGB::Yellow,
+    4 => Color::RGB::Orange,
+    5 => Color::RGB::Red,
+    6 => Color::RGB::Magenta,
+    7 => Color::RGB::DarkGray
+  }
+
+
+  gradient = Interpolation.new(points)
+
+  # what are the colors of the gradient from 0 to 7
+  # in increments of 0.2?
+  (0).step(7, 0.2) do |value|
+    color = gradient.at(value)
+    puts "A value of #{value} means #{color.html}"
+  end
+
+
+==Array-based Interpolations
+
+Aside from single value gradient points, you can interpolate over uniformly sized
+arrays.  Between two interpolation points, let's say +a+ and +b+, the final
+result will be +c+ where +c[0]+ is the interpolation of +a[0]+ and +b[0]+ and
++c[1]+ is interpolated between +a[1]+ and +b[1]+ and so on up to +c[n]+.
+
+Here is an example:
+
+  require 'rubygems'
+  require 'interpolate'
+  require 'pp'
+
+  # a non-linear set of multi-dimensional points;
+  # perhaps the location of some actor in relation to time
+  time_frames = {
+    0 => [0, 0, 0],
+    1 => [1, 0, 0],
+    2 => [0, 1, 0],
+    3 => [0, 0, 2],
+    4 => [3, 0, 1],
+    5 => [1, 2, 3],
+    6 => [0, 0, 0]
+  }
+
+  path = Interpolation.new(time_frames)
+
+  # play the actors 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:"
+    p position
+  end
+
+
+==Nested Array Interpolations
+
+As long as each top level array is uniformly sized in the first dimension
+and each nested array is uniformly sized in the second dimension (and so
+on...), multidimensional interpolation point values will just work.
+
+Here's an example of a set of 2D points being morphed:
+
+  require 'rubygems'
+  require 'interpolate'
+  require 'pp'
+
+
+  # a non-linear set of 2D vertexes;
+  # the shape changes at each frame
+  time_frames = {
+    0 => [[0, 0], [1, 0], [2, 0], [3, 0], [4, 0]], # a horizontal line
+    1 => [[0, 0], [1, 0], [3, 0], [0, 4], [0, 0]], # a triangle
+    2 => [[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]], # a square
+    3 => [[0, 0], [1, 0], [2, 0], [3, 0], [4, 0]], # a horizontal line, again
+    4 => [[0, 0], [0, 1], [0, 2], [0, 3], [0, 4]]  # a vertical line
+  }
+
+
+  paths = Interpolation.new(time_frames)
+
+  # show the vertex positions in time increments of 0.25
+  (0).step(4, 0.25) do |time|
+    points = paths.at(time)
+    puts ">> At #{time}s, points are:"
+    p points
+  end
+
+
+==License
+
+Licensed under the MIT license.
+
+=end
+
+
+# all numeric objects should be supported out of the box
+class Numeric
+  def interpolate(other, balance)
+    left = self.to_f
+    right = other.to_f
+    delta = (right - left).to_f
+    return left + (delta * balance)
+  end
+end
+
+
+# a little more complicated, but there's no reason why we can't
+# interpolate between two equal length arrays as long as each element
+# responds to :interpolate
+class Array
+  def interpolate(other, balance)
+    if (self.length < 1) then
+      raise ArgumentError, "cannot interpolate array with no values"
+    end
+
+    if (self.length != other.length) then
+      raise ArgumentError, "cannot interpolate between arrays of different length"
+    end
+
+    final = Array.new
+
+    self.each_with_index do |left, index|
+      unless (left.respond_to? :interpolate) then
+        raise "array element does not respond to :interpolate"
+      end
+
+      right = other[index]
+
+      final[index] = left.interpolate(right, balance)
+    end
+
+    return final
+  end
+end
+
+
+class Interpolation
+  VERSION = '0.2.0'
+
+  def initialize(points = {})
+    @points = {}
+    add!(points)
+  end
+
+  def add(points = {})
+    Interpolation.new(points.merge(@points))
+  end
+
+  def add!(points = {})
+    @points.merge!(points)
+    normalize_data
+  end
+
+
+  def at(point)
+    # deal with the two out-of-bounds cases first
+    if (point <= @min_point)
+      return @data.first.last
+    elsif (point >= @max_point)
+      return @data.last.last
+    end
+
+    # go through the interpolation intervals, in order, to determine
+    # into which this point falls
+    1.upto(@data.length - 1) do |zone|
+      left = @data.at(zone - 1)
+      right = @data.at(zone)
+      zone_range = left.first..right.first
+
+      if (zone_range.include?(point))
+        # what are the points in question?
+        left_point = left.first.to_f
+        right_point = right.first.to_f
+
+        # what are the values in question?
+        left_value = left.last
+        right_value = right.last
+
+        # span: difference between the left point and right point
+        # balance: ratio of right point to left point
+        span = right_point - left_point
+        balance = (point.to_f - left_point) / span
+
+        # catch the cases where the point in quesion is
+        # on one of the zone's endpoints
+        return left_value if (balance == 0.0)
+        return right_value if (balance == 1.0)
+
+        # otherwise, we need to interpolate
+        return left_value.interpolate(right_value, balance)
+      end
+    end
+
+    # we shouldn't get to this point
+    raise "couldn't come up with a value for some reason!"
+  end
+
+  private
+
+  def normalize_data
+    @data = @points.sort
+    @min_point = @data.first.first
+    @max_point = @data.last.first
+
+    # make sure that all values respond_to? :interpolate
+    @data.each do |point|
+      value = point.last
+      unless value.respond_to?(:interpolate)
+        raise ArgumentError, "found an interpolation point that doesn't respond to :interpolate"
+      end
+    end
+  end
+
+end
+
+

data/test/test_all.rb

@@ -0,0 +1,138 @@
+#!/usr/bin/env ruby1.8 -w
+
+require 'test/unit'
+require 'lib/interpolate'
+
+
+class InterpolationTest < Test::Unit::TestCase
+
+  DELTA = 1e-7
+
+  def setup
+    decimal_points = {
+      0 => 0,
+      1 => 0.1,
+      2 => 0.2,
+      3 => 0.3,
+      4 => 0.4,
+      5 => 0.5,
+      6 => 0.6,
+      7 => 0.7,
+      8 => 0.8,
+      9 => 0.9,
+      10 => 1
+    }
+
+    array_points = {
+      100 => [1,   10,  100],
+      200 => [5,   50,  500],
+      500 => [10, 100, 1000]
+    }
+
+    @dec_gradient = Interpolation.new(decimal_points)
+    @array_gradient = Interpolation.new(array_points)
+  end
+
+
+  def test_bad_points
+    bad_points = {
+      0 => 4.2,
+      1 => "hello", # not allowed by default
+      2 => 3.4,
+      3 => 4.8
+    }
+
+    assert_raise ArgumentError do
+      gradient = Interpolation.new(bad_points)
+    end
+
+  end
+
+  def test_lower_bounds
+    assert_equal(@dec_gradient.at(0), 0)
+    assert_equal(@dec_gradient.at(-1), 0)
+    assert_equal(@dec_gradient.at(-10), 0)
+    assert_equal(@dec_gradient.at(-100), 0)
+  end
+
+  def test_upper_bounds
+    assert_equal(@dec_gradient.at(10), 1)
+    assert_equal(@dec_gradient.at(100), 1)
+    assert_equal(@dec_gradient.at(1000), 1)
+  end
+
+  def test_midpoints
+    assert_in_delta(@dec_gradient.at(1.5), 0.15, DELTA)
+    assert_in_delta(@dec_gradient.at(2.5), 0.25, DELTA)
+    assert_in_delta(@dec_gradient.at(3.5), 0.35, DELTA)
+    assert_in_delta(@dec_gradient.at(4.5), 0.45, DELTA)
+    assert_in_delta(@dec_gradient.at(5.5), 0.55, DELTA)
+    assert_in_delta(@dec_gradient.at(6.5), 0.65, DELTA)
+    assert_in_delta(@dec_gradient.at(7.5), 0.75, DELTA)
+    assert_in_delta(@dec_gradient.at(8.5), 0.85, DELTA)
+    assert_in_delta(@dec_gradient.at(9.5), 0.95, DELTA)
+  end
+
+  def test_precision
+    assert_in_delta(@dec_gradient.at(1.5555), 0.15555, DELTA)
+    assert_in_delta(@dec_gradient.at(2.5678), 0.25678, DELTA)
+    assert_in_delta(@dec_gradient.at(3.5701), 0.35701, DELTA)
+  end
+
+  def test_gradient_add
+    new_points = {
+      11 => 1.1,
+      12 => 1.2,
+      13 => 1.3,
+      14 => 1.4,
+      15 => 1.5,
+      16 => 1.6,
+      17 => 1.7,
+      18 => 1.8,
+      19 => 1.9,
+      20 => 2
+    }
+
+    original = @dec_gradient.dup
+    expanded = original.add(new_points)
+
+    assert_equal(original.at(5), 0.5)
+    assert_equal(expanded.at(5), 0.5)
+
+    assert_equal(original.at(15), 1)
+    assert_equal(expanded.at(15), 1.5)
+  end
+
+  def test_gradient_add!
+    new_points = {
+      11 => 1.1,
+      12 => 1.2,
+      13 => 1.3,
+      14 => 1.4,
+      15 => 1.5,
+      16 => 1.6,
+      17 => 1.7,
+      18 => 1.8,
+      19 => 1.9,
+      20 => 2
+    }
+
+    original = @dec_gradient.dup
+    expanded = original.dup
+    expanded.add!(new_points)
+
+    assert_equal(original.at(5), 0.5)
+    assert_equal(expanded.at(5), 0.5)
+
+    assert_equal(original.at(15), 1)
+    assert_equal(expanded.at(15), 1.5)
+  end
+
+  def test_array_values
+    assert_equal(@array_gradient.at(150), [3, 30, 300])
+    assert_equal(@array_gradient.at(200), [5, 50, 500])
+    assert_equal(@array_gradient.at(350), [7.5, 75, 750])
+  end
+
+end
+

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: interpolate
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Adam Collins
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-01-24 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.4.0
+    version: 
+description: Library for creating generic interpolations objects.
+email: adam.w.collins@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- Manifest.txt
+- README.txt
+files: 
+- CHANGELOG
+- MIT-LICENSE
+- Manifest.txt
+- README.txt
+- Rakefile
+- examples/arrays.rb
+- examples/colors.rb
+- examples/nested.rb
+- examples/zones.rb
+- lib/interpolate.rb
+- test/test_all.rb
+has_rdoc: true
+homepage: http://interpolate.rubyforge.org
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: interpolate
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: 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.
+test_files: 
+- test/test_all.rb