interpolate 0.2.4 → 0.3.0

data/.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+*.swp
+Gemfile.lock
+.bundle/
+rdoc/
+pkg/
+*.gem

data/CHANGELOG.md

@@ -1,36 +1,46 @@
-== 0.2.4 (2011.4.10)
+## 0.3.0 (2012.9.01)
+
+Major gem revisions:
+
+* Interpolation class moved to Interpolate::Points
+* Binary search to find the correct interpolation interval
+* Optional blending function block can be passed to Interpolate::Points
+* gemspec file completely rebuilt, sans Jeweler
+
+## 0.2.4 (2011.4.10)
 
 * Project cleanup: minor updates to the lib/ file structure and documentation
 
-== 0.2.2 (2008.2.4)
+## 0.2.2 (2008.2.4)
 
-* Single source file has been split into Class files
-* Tests now use +freeze+
-* Better edge case testing in the Array and Numeric +interpolate+ methods
+* Single source file has been split into class files
+* Tests now use `freeze`
+* Better edge case testing in the `Array` and `Numeric` `interpolate` methods
 
-== 0.2.1 (2008.1.27)
+## 0.2.1 (2008.1.27)
 
 First public release
 
 Project Cleanup:
-  * Documentation enhancements and updates.
-  * +add+ is now +merge+
 
-== 0.2.0 (2008.1.24)
+* Documentation enhancements and updates.
+* `add` is now `merge`
+
+## 0.2.0 (2008.1.24)
 
 * Changed the library name to "interpolate"
-* Added +interpolate+ (+Array+) that covers uniform arrays and nested arrays
+* Added `Array#interpolate` that covers uniform arrays and nested arrays
 * Added more tests, documentation, and examples
 
-== 0.1.0 (2008.1.22)
+## 0.1.0 (2008.1.22)
 
-* 2 Major Changes:
+2 Major Changes:
 
-* Gadient calls +interpolate+ on values for OOP goodness
-* Checks added for respond_to? +interpolate+ on values
-* Added +interpolate+ (+Numeric+)
+* Gradient calls `interpolate` on values for OOP goodness
+* Checks added for `respond_to?(:interpolate)` on values
+* Added `Numeric#interpolate`
 
-== 0.0.1 (2008.1.20)
+## 0.0.1 (2008.1.20)
 
 * Initial coding
 * N-sized arbitrary floating point gradients

data/Gemfile

@@ -0,0 +1,5 @@
+source 'http://rubygems.org'
+
+gem 'rake'
+
+gemspec

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2008-2011 Adam Collins [adam@m104.us]
+Copyright (c) 2008-2012 Adam Collins [adam@m104.us]
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -7,126 +7,96 @@ Adam Collins [adam@m104.us]
 
 ## Description
 
-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.
+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.
 
 
 ## General Usage
 
-Specify the interpolation as a Hash, where keys represent numeric points
-along the gradient and values represent the known (key) values along that
-gradient.
-
-Here's an example for placing values within one of seven buckets:
-
-  require 'rubygems'
-  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,
-  }
-
-  bucketizer = Interpolation.new(buckets)
-
-  values = [
-    -20.2,
-    0.234,
-    65.24,
-    9.234,
-    398.4,
-    4000
-  ]
-
-  values.each do |value|
-    bucket = bucketizer.at(value).floor
-    puts "A value of #{value} falls into bucket #{bucket}"
-  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)
+Interpolation generators can be created with the Interpolate::Points class,
+given a Hash of "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.
+
+Here's an example for placing values within one of seven buckets, accomplished
+with the help of a `floor` blending function:
+
+    require 'rubygems'
+    require 'interpolate'
+
+    # min_value => bucket
+    buckets = {
+      0.000 => 1,
+      0.500 => 2,
+      1.250 => 3,
+      7.725 => 4,
+      28.85 => 5,
+      50.00 => 6,
+      127.5 => 7
+    }
+
+    values = [
+      -20.2,
+      0.234,
+      65.24,
+      9.234,
+      398.4,
+      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}"
     end
-  end
 
-  # a nice weathermap-style color gradient
-  points = {
-    1 => Color::RGB::White,
-    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
-  }
 
-  gradient = Interpolation.new(points)
 
-  # what are the colors of the gradient from 1 to 7
-  # in increments of 0.2?
-  (1).step(7, 0.2) do |value|
-    color = gradient.at(value)
-    puts "A value of #{value} means #{color.html}"
-  end
+## Array-based Interpolate::Points
 
-
-## 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 <tt>c[0]</tt> is the interpolation of <tt>a[0]</tt> and
-<tt>b[0]</tt> and <tt>c[1]</tt> is interpolated between <tt>a[1]</tt> and
-<tt>b[1]</tt> and so on up to <tt>c[n]</tt>.
+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 an actor in relation to time
-  time_frames = {
-    1 => [0, 0, 0],
-    2 => [1, 0, 0],
-    3 => [0, 1, 0],
-    4 => [0, 0, 2],
-    5 => [3, 0, 1],
-    6 => [1, 2, 3],
-    7 => [0, 0, 0]
-  }
-
-  path = Interpolation.new(time_frames)
-
-  # play the actor's positions in time increments of 0.25
-  (1).step(7, 0.25) do |time|
-    position = path.at(time)
-    puts ">> At #{time}s, actor is at:"
-    p position
-  end
+    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 = Interpolate::Points.new(time_frames)
+
+    # 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:"
+      p position
+    end
 
 
-## Nested Array Interpolations
+## Nested Array Interpolate::Points
 
 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
@@ -134,37 +104,80 @@ 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'
+    require 'rubygems'
+    require 'interpolate'
+    require 'pp'
+
+
+    # a number of sets 2D vertices, each set corresponding to a particular
+    # shape on the grid
+    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 = Interpolate::Points.new(time_frames)
 
-  # a number of sets 2D vertices, each set corresponding to a particular
-  # shape on the grid
-  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
-  }
+    # 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
+
+
+
+## Other Interpolations
+
+For other classes of value objects, you'll need to implement a blending
+function.  Here's an example using an RGB color gradient with the help of the
+'color' gem:
 
 
-  paths = Interpolation.new(time_frames)
+    require 'rubygems'
+    require 'interpolate'
+    require 'color'
 
-  # 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
+    # a nice weathermap-style color gradient
+    points = {
+      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,
+      8 => Color::RGB::White,
+    }
+
+    # 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 8
+    # in increments of 0.2?
+    (1).step(7, 0.2) do |value|
+      color = gradient.at(value)
+      puts "A value of #{value.round(3)} means #{color.html}"
+    end
 
 
 ## License
 
 (The MIT License)
 
-Copyright (c) 2008-2011 Adam Collins [adam@m104.us]
+Copyright (c) 2008-2012 Adam Collins [adam@m104.us]
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/Rakefile

@@ -1,35 +1,21 @@
-require 'jeweler'
-require 'rake'
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require 'interpolate'
 
-require './lib/interpolate/interpolation'
-
-Jeweler::Tasks.new do |g|
-  doc_sections = File.read('README.md').delete("\r").split(/^## /)
+desc 'Build the gem'
+task :build do
+  system 'gem build interpolate.gemspec'
+end
 
-  g.name = 'interpolate'
-  g.summary = 'Create linear interpolations from key points and values'
-  g.description = doc_sections[2].chomp.chomp # mmmm... tasty!
-  g.email = 'adam@m104.us'
-  g.homepage = "http://github.com/m104/interpolate"
-  g.authors = ["Adam Collins"]
-  g.version = Interpolation::VERSION
+desc 'Release the gem'
+task :release => :build do
+  system "gem push interpolate-#{Interpolation::VERSION}"
 end
 
 require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.test_files = FileList.new('test/test_*.rb') do |list|
-    list.exclude 'test/test_helper.rb'
-  end
-  test.libs << 'test'
-  test.verbose = true
-end
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = 'interpolate'
-  rdoc.rdoc_files.include('README.markdown')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+Rake::TestTask.new do |t|
+  t.libs << 'test'
 end
 
+task :default => :test
 

data/TODO

@@ -0,0 +1,14 @@
+Interpolate::Points
+  - out of bounds behavior options
+  - more than one stock blending function
+  - allow symbol in place of blend_with Proc
+
+Add/Core
+  - Complex type :interpolate method
+
+Testing
+  - more coverage of blending function behavior
+  - split test_all.rb into case category files
+  - minitest
+  - contexts (?)
+