bezier_curve 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7bdfef0208f447bf444392f207505bcf076d56db
+  data.tar.gz: fffe1353eca9734c7b1e5a8076a0da179bfd0435
+SHA512:
+  metadata.gz: 7b57e98d8ffcd9ac90b1d969e3728890bc654493d56006d8ec5a5d39f4386e6b6eb5252a6272bfc8c10511130b5bf7f0cbaedcfb8c62ae2779dedf9092119818
+  data.tar.gz: e8f69f9b96cb70bed85e8f70167247e33ecd26dd9536061c822b0773f4391b8f274303fc95958d1afc881b549d6c42c6f39d52a787fc15e615b8842bf16b6e8a

data/README.md

@@ -0,0 +1,44 @@
+# bezier_curve
+A bézier curve library for Ruby, supporting n-dimensional, nth-degree curves
+
+A rather simple and small library that should do pretty much anything you need to do with a bezier curve. It supports arbitrary numbers of dimensions, and arbitrary numbers of control points. Even still, it is pretty easy to use. Here's a simple quadratic (1st degree) bezier curve, in 2-dimensional space:
+
+    # create the curve
+    curve = BezierCurve.new([0,0],[0,1],[1,1])
+    # determine its points for drawing purposes
+    curve.points
+    [[0, 0], [0.00390625, 0.12109375], ... [0.87890625, 0.99609375], 1, 1]
+
+When outputting points, it automatically chooses a suitable angle tolerance which would make the resulting poly-line appear relatively smooth (no angle changes more than about 3 degrees). But you can choose your own tolerance:
+    
+    # Extreme precision, less than 1 degree tolerance
+    curve.points(tolerance: Math::PI/180)
+    # just give me 5 points, quick: 
+    curve.points(count: 5)
+
+You can easily split a curve into two, at a given value of `t`
+    
+    # split the curve at its midpoint
+    curve.split_at(0.5)
+      #=> [BezierCurve([0, 0], [0.0, 0.5], [0.25, 0.75]), BezierCurve([0.25, 0.75], [0.5, 1.0], [1, 1])]
+    
+You can also specify n-dimensional curves:
+    
+    # a 4-dimensional curve of 2nd order
+    curve = BezierCurve.new([0,0,0,0], [1,1,2,2], [4,5,9,3])
+    # get its points
+    curve.points(count:3)
+        #=> [[0.0, 0.0, 0.0, 0.0], [1.5, 1.75, 3.25, 1.75], [4.0, 5.0, 9.0, 3.0]]
+    
+You can also specify any degree/order of curve you like:
+    
+    # 2d curve, 6th degree
+    curve = BezierCurve.new([0,0],[1,1],[2,-1],[3,1],[4,-1],[5,1],[6,-1])
+    curve.degree
+      #=> 6
+    curve.points.size
+      #=> 35
+    
+Note that the complexity goes up exponentially for higher degree curves, so performance may suffer if used extensively; but the capability is there if you need it. In fact, if you want, you can really slow things down and do a 18-dimensional curve of the 300th order. The sky is the limit. Well, your processor and memory are the limit, but you get the idea.
+
+I am interested in making this the most useful ruby library for working with bezier curves. If you need help, or have a suggestion for improvement, feel free to file an issue on Github (https://github.com/marcuserronius/bezier_curve/), or contact me directly.

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/lib/bezier_curve/n_point.rb

@@ -0,0 +1,46 @@
+# bezier_curve/n_point.rb
+
+# Extends an array to treat it as an n-dimensional point. Should not
+# occlude any original Array methods
+module NPoint
+  # calculates how far this point is from `other`
+  def dist_from(other)
+    raise "Dimension counts don't match! (%i and %i)" %[size,other.size] unless size == other.size
+    zip(other).map{|a,b|(a-b)**2}.inject{|a,b|a+b}**0.5
+  end
+  # calculates the angle formed by this point and two others
+  # in radians
+  def angle_to(a,b)
+    a,b = *[a,b].map(&:to_np)
+    d0,d1 = dist_from(a), a.dist_from(b)
+    z = self.to(a,1+d1/d0)
+    dz = z.dist_from(b)
+    Math.asin(dz/2/d1)*2
+  end
+
+  # calculates the new point on the vector of self->other, scaled by `t`.
+  # t=0 returns `self`, t=.5 is the midpoint, t=1 is `other`.
+  def to(other, t)
+    self.zip(other).map{|a,b|t*(b-a)+a}.to_np
+  end
+
+  # convert to NPoint; returns self
+  def to_np
+    self
+  end
+
+  # get the x value
+  def x() self[0]; end
+  # get the y value
+  def y() self[1]; end
+  # get the z value
+  def z() self[2]; end
+end
+
+
+class Array
+  # add n-point functions to a copy of this array
+  def to_np
+    dup.extend NPoint
+  end
+end

data/lib/bezier_curve/version.rb

@@ -0,0 +1,7 @@
+# bezier_curve/version.rb
+# Just the version information for this library
+
+class BezierCurve
+  VERSION       = "0.8.0"
+  RELEASE_DATE  = "2015-06-18"
+end

data/lib/bezier_curve.rb

@@ -0,0 +1,151 @@
+# bezier_curve.rb
+# A bézier curve library for Ruby, supporting n-dimensional,
+# nth-degree curves.
+
+require 'bezier_curve/version'
+require 'bezier_curve/n_point'
+
+# A bezier curve. Usage:
+#   c = BezierCurve.new([0,0], [0,1], [1,1])
+#   c.first             #=> [0,0]
+#   c.last              #=> [1,1]
+#   c[0.375]            #=> [t=.375]
+#   c.points            #=> an array of points that make a fairly smooth curve
+#   c.points(tolerance:Math::PI/20)
+#                       #=> returns points with given tolerance for smoothness
+#   c.points(count: 10) #=> returns 10 points, for evenly spaced values of `t`
+class BezierCurve
+  # create a new curve, from a list of points.
+  def initialize(*controls)
+    # check for argument errors
+    ZeroDimensionError.check! controls
+    DifferingDimensionError.check! controls
+    InsufficientPointsError.check! controls
+
+    @controls = controls.map(&:to_np)
+  end
+
+  attr_reader :controls
+
+  # the first control point
+  def first() controls.first; end
+  alias_method :start, :first
+  # the last control point
+  def last()  controls.last;  end
+  alias_method :end, :last
+  
+  # the degree of the curve
+  def degree
+    controls.size - 1
+  end
+  alias_method :order, :degree
+  # the number of dimensions given
+  def dimensions
+    controls[0].size
+  end
+
+  # find the point for a given value of `t`.
+  def index(t)
+    pts = controls
+    while pts.size > 1
+      pts = (0..pts.size-2).map do |i|
+        pts[i].zip(pts[i+1]).map{|a,b| t*(b-a)+a}
+      end
+    end
+    pts[0].to_np
+  end
+  alias_method :[], :index
+
+  # divide this bezier curve into two curves, at the given `t`
+  def split_at(t)
+    pts = controls
+    a,b = [pts.first],[pts.last]
+    while pts.size > 1
+      pts = (0..pts.size-2).map do |i|
+        pts[i].zip(pts[i+1]).map{|a,b| t*(b-a)+a}
+      end
+      a<<pts.first
+      b<<pts.last
+    end
+    [BezierCurve.new(*a), BezierCurve.new(*b.reverse)]
+  end
+
+
+  # Returns a list of points on this curve. If you specify `count`,
+  # returns that many points, evenly spread over values of `t`.
+  # If you specify `tolerance`, no adjoining line segments will
+  # deviate from 180 by an angle of more than the value given (in
+  # radians). If unspecified, defaults to `tolerance: 1/64pi` (~3 deg)
+  def points(count:nil, tolerance:Math::PI/64)
+    if count
+      (0...count).map{|i| index i/(count-1.0)}
+    else
+      lines = subdivide(tolerance)
+      lines.map{|seg|seg.first} + [lines.last.last]
+    end
+  end
+
+  # recursively subdivides the curve until each is straight within the
+  # given tolerance value, in radians
+  def subdivide(tolerance)
+    if is_straight?(tolerance)
+      [self]
+    else
+      a,b = split_at(0.5)
+      a.subdivide(tolerance) + b.subdivide(tolerance)
+    end
+  end
+
+
+  # test this curve to see of it can be considered straight, optionally
+  # within the given angular tolerance, in radians
+  def is_straight?(tolerance)
+    # sanity check for tolerance in radians
+    if first.angle_to(index(0.5), last) <= tolerance
+      # maximum wavyness is `degree` - 1; split at `degree` points
+      pts = points(count:degree)
+      # size-3, because we ignore the last 2 points as starting points;
+      # check all angles against `tolerance`
+      (0..pts.size-3).all? do |i|
+        pts[i].angle_to(pts[i+1], pts[i+2]) < tolerance
+      end
+    end
+  end
+
+  # Indicates an error where the control points are in zero dimensions.
+  # Sounds silly, but you never know when software is generating the
+  # points.
+  class ZeroDimensionError < ArgumentError
+    def initialize
+      super "Points given must have at least one dimension"
+    end
+    def self.check! pointset
+      raise new.tap{|e|e.backtrace.shift} if
+        pointset[0].size == 0
+    end
+  end
+
+  # Indicates that the points do not all have the same number of
+  # dimensions, which makes them impossible to use.
+  class DifferingDimensionError < ArgumentError
+    def initialize
+      super "All points must have the same number of dimensions"
+    end
+    def self.check! pointset
+      raise new.tap{|e|e.backtrace.shift} if
+        pointset[1..-1].any?{|pt| pointset[0].size != pt.size}
+    end
+  end
+
+  # Indicates that there aren't enough control points; minimum of two
+  # for a first-degree bezier.
+  class InsufficientPointsError < ArgumentError
+    def initialize
+      super "All points must have the same number of dimensions"
+    end
+    def self.check! pointset
+      raise new.tap{|e|e.backtrace.shift} if
+        pointset.size <= 1
+    end
+  end
+end

data/test/test_bezier_curve.rb

@@ -0,0 +1,104 @@
+# test functionality of BezierCurve class
+require 'test/unit'
+require 'bezier_curve'
+
+class TestBezierCurve < Test::Unit::TestCase
+  # shorthand to create a bezier curve
+  def bc(*args)
+    BezierCurve.new(*args)
+  end
+
+  def test_degree
+    assert_equal 2, bc([0,0],[0,1],[1,1]).degree
+    assert_equal 3, bc([0,0],[0,1],[1,0],[1,1]).degree
+  end
+
+  def test_dimensions
+    assert_equal 2, bc([0,0],[0,1],[1,1]).dimensions
+    assert_equal 3, bc([0,0,0],[0,1,1],[1,1,2]).dimensions
+  end
+
+  def test_index
+    # simple curves that cross the origin
+    # degree 1
+    assert_equal [0,0], bc([1,1],[-1,-1])[0.5]
+    assert_equal [0,0,0], bc([1,1,1],[-1,-1,-1])[0.5]
+    assert_equal [0,0,0,0], bc([1,1,1,1],[-1,-1,-1,-1])[0.5]
+    assert_equal [0,0,0,0,0], bc([1,1,1,1,1],[-1,-1,-1,-1,-1])[0.5]
+    # degree 2 (quadratic)
+    assert_equal [0,0], bc([1,1],[0,-1],[-1,1])[0.5]
+    assert_equal [0,0,0], bc([1,1,1],[0,0,-1],[-1,-1,1])[0.5]
+    assert_equal [0,0,0,0], bc([1,1,1,1],[0,0,0,-1],[-1,-1,-1,1])[0.5]
+    assert_equal [0,0,0,0,0], bc([1,1,1,1,1],[0,0,0,0,-1],[-1,-1,-1,-1,1])[0.5]
+    # degree 3 (cubic)
+    assert_equal [0,0], bc([1,1],[-1,1],[1,-1],[-1,-1])[0.5]
+    assert_equal [0,0,0], bc([1,1,1],[-1,1,1],[1,-1,-1],[-1,-1,-1])[0.5]
+    assert_equal [0,0,0,0], bc([1,1,1,1],[-1,1,1,1],[1,-1,-1,-1],[-1,-1,-1,-1])[0.5]
+    assert_equal [0,0,0,0,0], bc([1,1,1,1,1],[-1,1,1,1,1],[1,-1,-1,-1,-1],[-1,-1,-1,-1,-1])[0.5]
+  end
+  def test_split_at
+    # not going to test specific points, just that the resulting curves are the same
+    # degree 1
+    c = bc([23,42],[13,7])
+    _c1, _c2 = *c.split_at(0.25)
+    assert_equal c.points(count:9), _c1.points(count:3)[0,2] + _c2.points(count:7)
+    # degree 2
+    c = bc([23,42],[13,7])
+    _c1, _c2 = *c.split_at(0.25)
+    assert_equal c.points(count:9), _c1.points(count:3)[0,2] + _c2.points(count:7)
+    # degree 3
+    c = bc([23,42,],[13,7],[12,54])
+    _c1, _c2 = *c.split_at(0.25)
+    assert_equal c.points(count:9), _c1.points(count:3)[0,2] + _c2.points(count:7)
+    # degree 4
+    c = bc([23,42],[13,7],[12,54],[103,144])
+    _c1, _c2 = *c.split_at(0.25)
+    assert_equal c.points(count:9), _c1.points(count:3)[0,2] + _c2.points(count:7)
+    # degree 5
+    c = bc([23,42],[13,7],[12,54],[103,144],[512,360])
+    _c1, _c2 = *c.split_at(0.25)
+    assert_equal c.points(count:9), _c1.points(count:3)[0,2] + _c2.points(count:7)
+  end
+  # does this really need testing? I really hope not. Oh well.
+  def test_points_count
+    # 1d,o1
+    [2,3,5,8,13,23].each do |n|
+      assert_equal n, bc([0,0],[1,1]).points(count:n).count
+    end
+    # 2d,o2
+    [2,3,5,8,13,23].each do |n|
+      assert_equal n, bc([0,0,0],[1,1,1],[2,2,2]).points(count:n).count
+    end
+    # 3d,o3
+    [2,3,5,8,13,23].each do |n|
+      assert_equal n, bc(*4.times.map{|n|Array.new(4).fill(n)}).points(count:n).count
+    end
+    # 4d,o4
+    [2,3,5,8,13,23].each do |n|
+      assert_equal n, bc(*5.times.map{|n|Array.new(5).fill(n)}).points(count:n).count
+    end
+    # 5d,o5
+    [2,3,5,8,13,23].each do |n|
+      assert_equal n, bc(*6.times.map{|n|Array.new(6).fill(n)}).points(count:n).count
+    end
+  end
+
+  def test_points_tolerance
+    pi = Math::PI
+    # just make sure all points are under tolerance
+    # 2d/o
+    p = bc([1,0],[3,2],[7,9]).points(tolerance:pi/53)
+    assert_true (0..p.count-3).all?{|i|p[i].angle_to(p[i+1],p[i+2]).abs < pi/53}
+    # 3d/o
+    p = bc([1,0,2],[3,2,5],[7,9,8],[13,17,12]).points(tolerance:pi/53)
+    assert_true (0..p.count-3).all?{|i|p[i].angle_to(p[i+1],p[i+2]).abs < pi/53}
+    # 4d/o
+    p = bc([1,0,2,-1],[3,2,5,4],[7,9,8,6],[13,17,12,15],[20,21,32,25]).points(tolerance:pi/53)
+    assert_true (0..p.count-3).all?{|i|p[i].angle_to(p[i+1],p[i+2]).abs < pi/53}
+    # 5d/o
+    p = bc([1,0,2,-1,3],[3,2,5,4,6],[7,9,8,6,5],[13,17,12,15,14],[20,21,32,25,23],[34,33,47,39,52]).points(tolerance:pi/53)
+    assert_true (0..p.count-3).all?{|i|p[i].angle_to(p[i+1],p[i+2]).abs < pi/53}
+  end
+
+end
+

data/test/test_n_point.rb

@@ -0,0 +1,51 @@
+# test functionality of NPoint module
+require 'test/unit'
+require 'bezier_curve/n_point'
+
+class TestNPoint < Test::Unit::TestCase
+  def test_to_np
+    np = [9,8,7].to_np
+
+    assert_kind_of  NPoint, np,   "Array#to_np should return an NPoint" 
+    assert_same     np.to_np, np, "NPoint#to_np should return self"
+  end
+  def test_x
+    np = [9,8,7].to_np
+    assert_equal 9, np.x
+  end
+  def test_y
+    np = [9,8,7].to_np
+    assert_equal 8, np.y
+  end
+  def test_z
+    np = [9,8,7].to_np
+    assert_equal 7, np.z
+  end
+  def test_to
+    a, b = [1,1,1].to_np, [5,5,5].to_np
+
+    assert_equal [3,3,3], a.to(b,0.5)
+    assert_equal [-1,-1,-1], a.to(b,-0.5)
+    assert_equal [7,7,7], a.to(b,1.5)
+  end
+  def test_dist_from
+    # various numbers of dimensions
+    assert_equal 3,             [3].to_np.dist_from([6])
+    assert_equal (3**2*2)**0.5, [3,3].to_np.dist_from([6,6])
+    assert_equal (3**2*3)**0.5, [3,3,3].to_np.dist_from([6,6,6])
+    assert_equal (3**2*4)**0.5, [3,3,3,3].to_np.dist_from([6,6,6,6])
+    assert_equal (3**2*5)**0.5, [3,3,3,3,3].to_np.dist_from([6,6,6,6,6])
+
+    # across the origin
+    assert_in_delta  8**0.5, [1,1].to_np.dist_from([-1,-1]), 0.00001
+  end
+  def test_angle_to
+    pi = Math::PI
+    pi_eps = (pi.next_float-pi)*16
+    assert_in_epsilon pi/2,  [1,0].to_np.angle_to([0,0],[0,1]),   pi_eps
+    assert_in_epsilon pi,    [1,1].to_np.angle_to([0,0],[1,1]),   pi_eps
+    assert_in_epsilon 0,     [1,1].to_np.angle_to([0,0],[-1,-1]), pi_eps
+    assert_in_epsilon pi/4,  [-1,0].to_np.angle_to([0,0],[1,1]),  pi_eps
+  end
+end
+

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: bezier_curve
+version: !ruby/object:Gem::Version
+  version: 0.8.0
+platform: ruby
+authors:
+- Mark Hubbart
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-06-18 00:00:00.000000000 Z
+dependencies: []
+description: A bézier curve library for Ruby, supporting n-dimensional, nth-degree
+  curves
+email: mark.hubbart@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/bezier_curve.rb
+- lib/bezier_curve/n_point.rb
+- lib/bezier_curve/version.rb
+- test/test_bezier_curve.rb
+- test/test_n_point.rb
+homepage: https://github.com/marcuserronius/bezier_curve
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: N-dimensional, nth-degree bézier curves
+test_files: []