geometry 6 → 6.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ed229b8577bfe815ff25060d851e6f27515cf7a7
+  data.tar.gz: 9ed183df010e991b72c216639acda3f2f68884d5
+SHA512:
+  metadata.gz: ea42b04b4aa1bc9f89f5d64cc2e96ff61a066bff34108d6b534e492da37dd69a7aa8163f5388bb46ae350c726926074d9a201480d642c376518bf3efc63c631b
+  data.tar.gz: bafb8c4996b9017d28f43d7b56a0b1e253d738f20ade966aa196efca041513f2ebd502be560926a3404b9314c04ce3f13e4c8c382e2a1dd06d797062ada2c7ac

data/README.markdown

@@ -14,7 +14,7 @@ that don't work in higher dimensions and I'll do my best to fix them.
 License
 -------
 
-Copyright 2012-2013 Brandon Fosdick <bfoz@bfoz.net> and released under the BSD license.
+Copyright 2012-2014 Brandon Fosdick <bfoz@bfoz.net> and released under the BSD license.
 
 Primitives
 ----------
@@ -45,6 +45,11 @@ Examples
     point.x
     point.y
     point[2]	# Same as point.z
+
+    # Zero
+    PointZero.new   # A Point full of zeros of unspecified length
+    Point.zero      # Another way to do the same thing
+    Point.zero(3)   # => Point[0,0,0]
 ```
 
 ### Line

data/Rakefile

@@ -5,7 +5,6 @@ task :default => :test
 
 Rake::TestTask.new do |t|
     t.libs.push "lib"
-#    t.test_files = FileList['test/**/rectangle.rb']
     t.test_files = FileList['test/**/*.rb']
     t.verbose = true
 end

data/geometry.gemspec

@@ -3,7 +3,7 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = "geometry"
-  s.version     = '6'
+  s.version     = '6.1'
   s.authors     = ["Brandon Fosdick"]
   s.email       = ["bfoz@bfoz.net"]
   s.homepage    = "http://github.com/bfoz/geometry"

data/lib/geometry/line.rb

@@ -87,6 +87,9 @@ Supports two-point, slope-intercept, and point-slope initializer forms
 
     # @private
     class PointSlopeLine < Line
+	# @return [Number]  the slope of the {Line}
+	attr_reader :slope
+
 	def initialize(point, slope)
 	    @point = Point[point]
 	    @slope = slope
@@ -98,6 +101,9 @@ Supports two-point, slope-intercept, and point-slope initializer forms
 
     # @private
     class SlopeInterceptLine < Line
+	# @return [Number]  the slope of the {Line}
+	attr_reader :slope
+
 	def initialize(slope, intercept)
 	    @slope = slope
 	    @intercept = intercept
@@ -118,9 +124,6 @@ Supports two-point, slope-intercept, and point-slope initializer forms
 		    vertical? ? nil : @intercept
 	    end
 	end
-	def slope
-	    @slope
-	end
 
 	def to_s
 	    'Line(' + @slope.to_s + ',' + @intercept.to_s + ')'
@@ -138,6 +141,14 @@ Supports two-point, slope-intercept, and point-slope initializer forms
 	    'Line(' + @first.inspect + ', ' + @last.inspect + ')'
 	end
 	alias :to_s :inspect
+
+# @group Accessors
+	# !@attribute [r[ slope
+	#   @return [Number]	the slope of the {Line}
+	def slope
+	    (last.y - first.y)/(last.x - first.x)
+	end
+# @endgroup
     end
 end
 

data/lib/geometry/point.rb

@@ -35,10 +35,16 @@ geometry class (x, y, z).
 	    super *array
 	end
 
-	# Creates and returns a new {PointZero} instance
+	# Creates and returns a new {PointZero} instance. Or, a {Point} full of zeros if the size argument is given.
+	# @param size [Number] the size of the new {Point} full of zeros
 	# @return [PointZero] A new {PointZero} instance
-	def self.zero
-	    PointZero.new
+	def self.zero(size=nil)
+	    size ? Point[Array.new(size, 0)] : PointZero.new
+	end
+
+	# Return a copy of the {Point}
+	def clone
+	    Point[@elements.clone]
 	end
 
 	# Allow comparison with an Array, otherwise do the normal thing
@@ -128,8 +134,8 @@ geometry class (x, y, z).
 	    case other
 		when Numeric
 		    Point[@elements.map {|e| e + other}]
-		when PointZero
-		    self
+		when PointZero, NilClass
+		    self.dup
 		else
 		    raise OperationNotDefined, "#{other.class} must respond to :size and :[]" unless other.respond_to?(:size) && other.respond_to?(:[])
 		    raise DimensionMismatch,  "Can't add #{other} to #{self}" if size != other.size
@@ -141,8 +147,8 @@ geometry class (x, y, z).
 	    case other
 		when Numeric
 		    Point[@elements.map {|e| e - other}]
-		when PointZero
-		    self
+		when PointZero, NilClass
+		    self.dup
 		else
 		    raise OperationNotDefined, "#{other.class} must respond to :size and :[]" unless other.respond_to?(:size) && other.respond_to?(:[])
 		    raise DimensionMismatch, "Can't subtract #{other} from #{self}" if size != other.size

data/lib/geometry/point_zero.rb

@@ -5,7 +5,8 @@ module Geometry
 An object repesenting a {Point} at the origin in N-dimensional space
 
 A {PointZero} object is a {Point} that will always compare equal to zero and unequal to
-everything else, regardless of size.
+everything else, regardless of size. You can think of it as an application of the
+{http://en.wikipedia.org/wiki/Null_Object_pattern Null Object Pattern}.
 =end
     class PointZero
 	def eql?(other)
@@ -42,19 +43,19 @@ everything else, regardless of size.
 	end
 
 	# @attribute [r] x
-	# @return [Numeric] X-component
+	#   @return [Numeric] X-component
 	def x
 	    0
 	end
 
 	# @attribute [r] y
-	# @return [Numeric] Y-component
+	#   @return [Numeric] Y-component
 	def y
 	    0
 	end
 
 	# @attribute [r] z
-	# @return [Numeric] Z-component
+	#   @return [Numeric] Z-component
 	def z
 	    0
 	end

data/lib/geometry/polygon.rb

@@ -29,9 +29,13 @@ but there's currently nothing that enforces simplicity.
 	#   @return [Polygon]
 	def initialize(*args)
 	    super
+	    close!	# A Polygon is always closed
+	end
 
-	    # Close the polygon if needed
-	    @edges.push Edge.new(@edges.last.last, @edges.first.first) unless @edges.empty? || (@edges.last.last == @edges.first.first)
+	# This method returns the receiver because a {Polygon} is always closed
+	# @return [Polygon]	the receiver
+	def close
+	    close!
 	end
 
 	# Check the orientation of the {Polygon}
@@ -45,6 +49,19 @@ but there's currently nothing that enforces simplicity.
 	    self.class.new *(self.vertices.reverse)
 	end
 
+	# Reverse the receiver and return it
+	# @return [Polygon]	the reversed receiver
+	def reverse!
+	    super
+
+	    # Simply reversing the vertex array causes the reversed polygon to
+	    #  start at what had been the last vertex, instead of starting at
+	    #  the same vertex and just going the other direction.
+	    vertices.unshift vertices.pop
+
+	    self
+	end
+
 	# @group Boolean operators
 
 	# Test a {Point} for inclusion in the receiver using a simplified winding number algorithm
@@ -205,16 +222,16 @@ but there's currently nothing that enforces simplicity.
 	# @param [Number] distance	The distance to offset by
 	# @return [Polygon] A new {Polygon} outset by the given distance
 	def outset(distance)
-	    bisectors = offset_bisectors(distance)
-	    offsets = (bisectors.each_cons(2).to_a << [bisectors.last, bisectors.first])
+	    bisector_edges = outset_bisectors(distance)
+	    bisector_pairs = bisector_edges.push(bisector_edges.first).each_cons(2)
 
 	    # Create the offset edges and then wrap them in Hashes so the edges
 	    #  can be altered while walking the array
-	    active_edges = edges.zip(offsets).map do |e,offset|
-		offset = Edge.new(e.first+offset.first.vector, e.last+offset.last.vector)
+	    active_edges = edges.zip(bisector_pairs).map do |e,offset|
+		offset_edge = Edge.new(e.first+offset.first.vector, e.last+offset.last.vector)
 
 		# Skip zero-length edges
-		{:edge => (offset.first == offset.last) ? nil : offset}
+		{:edge => (offset_edge.first == offset_edge.last) ? nil : offset_edge}
 	    end
 
 	    # Walk the array and handle any intersections
@@ -239,6 +256,7 @@ but there's currently nothing that enforces simplicity.
 			# Handle the collinear case
 			active_edges[i][:edge] = Edge.new(e1.first, e2.last)
 			active_edges[j].delete(:edge)
+			wrap_around_is_shortest = false
 		    end
 
 		    # Delete everything between e1 and e2
@@ -263,29 +281,17 @@ but there's currently nothing that enforces simplicity.
 	    Polygon.new *(active_edges.map {|e| e[:edge]}.compact.map {|e| [e.first, e.last]}.flatten)
 	end
 
-	# Vertex bisectors suitable for offsetting
+	# Vertex bisectors suitable for outsetting
 	# @param [Number] length    The distance to offset by
 	# @return [Array<Edge>]	{Edge}s representing the bisectors
-	def offset_bisectors(length)
-	    vectors = edges.map {|e| e.direction }
-	    winding = 0
-	    sums = vectors.unshift(vectors.last).each_cons(2).map do |v1,v2|
-		k = v1[0]*v2[1] - v1[1]*v2[0]	# z-component of v1 x v2
-		winding += k
-		if v1 == v2			# collinear, same direction?
-		    Vector[-v1[1], v1[0]]
-		elsif 0 == k			# collinear, reverse direction
-		    nil
-		else
-		    by = (v2[1] - v1[1])/k
-		    v = (0 == v1[1]) ? v2 : v1
-		    Vector[(v[0]*by - 1)/v[1], by]
-		end
-	    end
+	def outset_bisectors(length)
+	    vertices.zip(spokes).map {|v,b| b ? Edge.new(v, v+(b * length)) : nil}
+	end
 
-	    # Check the polygon's orientation. If clockwise, negate length as a hack for injecting a -1 into the final result
-	    length = -length if winding >= 0
-	    vertices.zip(sums).map {|v,b| b ? Edge.new(v, v+(b * length)) : nil}
+	# Generate the unit-length spokes for each vertex
+	# @return [Array<Vector>]   the unit {Vector}s representing the spoke of each vertex
+	def spokes
+	    clockwise? ? left_bisectors : right_bisectors
 	end
 
 	private

data/lib/geometry/polyline.rb

@@ -16,7 +16,7 @@ also like a {Path} in that it isn't necessarily closed.
 	attr_reader :edges, :vertices
 
 	# Construct a new Polyline from Points and/or Edges
-	#  The constructor will try to convert all of its arguments into {Point}s and
+	# @note The constructor will try to convert all of its arguments into {Point}s and
 	#   {Edge}s. Then successive {Point}s will be collpased into {Edge}s. Successive
 	#   {Edge}s that share a common vertex will be added to the new {Polyline}. If
 	#   there's a gap between {Edge}s it will be automatically filled with a new
@@ -94,21 +94,94 @@ also like a {Path} in that it isn't necessarily closed.
 	end
 	alias :== :eql?
 
-	# Offset the receiver by the specified distance. A positive distance
-	#  will offset to the left, and a negative distance to the right.
+	# Clone the receiver, close it, then return it
+	# @return [Polyline]	the closed clone of the receiver
+	def close
+	    clone.close!
+	end
+
+	# Close the receiver and return it
+	# @return [Polyline]	the receiver after closing
+	def close!
+	    push_edge Edge.new(@edges.last.last, @edges.first.first) unless @edges.empty? || closed?
+	    self
+	end
+
+	# Check to see if the {Polyline} is closed (ie. is it a {Polygon}?)
+	# @return [Bool] true if the {Polyline} is closed (the first vertex is equal to the last vertex)
+	def closed?
+	    @edges.last.last == @edges.first.first
+	end
+
+	# Clone the receiver, reverse it, then return it
+	# @return [Polyline]	the reversed clone
+	def reverse
+	    self.class.new *(edges.reverse.map! {|edge| edge.reverse! })
+	end
+
+	# Reverse the receiver and return it
+	# @return [Polyline]	the reversed receiver
+	def reverse!
+	    vertices.reverse!
+	    edges.reverse!.map! {|edge| edge.reverse! }
+	    self
+	end
+
+	# @group Bisectors
+
+	# Generate the angle bisector unit vectors for each vertex
+	# @note If the {Polyline} isn't closed (the normal case), then the first and
+	#   last vertices will be given bisectors that are perpendicular to themselves.
+	# @return [Array<Vector>]   the unit {Vector}s representing the angle bisector of each vertex
+	def bisectors
+	    # Multiplying each bisector by the sign of k flips any bisectors that aren't pointing towards the interior of the angle
+	    bisector_map {|b, k| k <=> 0 }
+	end
+
+	# Generate left-side angle bisector unit vectors for each vertex
+	# @note This is similar to the #bisector method, but generates vectors that always point to the left side of the {Polyline} instead of towards the inside of each corner
+	# @return [Array<Vector>]   the unit {Vector}s representing the left-side angle bisector of each vertex
+	def left_bisectors
+	    bisector_map
+	end
+
+	# Generate right-side angle bisector unit vectors for each vertex
+	# @note This is similar to the #bisector method, but generates vectors that always point to the right side of the {Polyline} instead of towards the inside of each corner
+	# @return [Array<Vector>]   the unit {Vector}s representing the ride-side angle bisector of each vertex
+	def right_bisectors
+	    bisector_map {|b, k| -1 }
+	end
+
+	# Generate the spokes for each vertex. A spoke is the same as a bisector, but in the oppostire direction (bisectors point towards the inside of each corner; spokes point towards the outside)
+	# @note If the {Polyline} isn't closed (the normal case), then the first and
+	#   last vertices will be given bisectors that are perpendicular to themselves.
+	# @return [Array<Vector>]   the unit {Vector}s representing the spoke of each vertex
+	def spokes
+	    # Multiplying each bisector by the negated sign of k flips any bisectors that aren't pointing towards the exterior of the angle
+	    bisector_map {|b, k| 0 <=> k }
+	end
+
+	# @endgroup Bisectors
+
+	# Offset the receiver by the specified distance
+	# @note A positive distance will offset to the left, and a negative distance to the right.
 	# @param [Number] distance	The distance to offset by
-	# @return [Polygon] A new {Polygon} outset by the given distance
+	# @return [Polyline] A new {Polyline} outset by the given distance
 	def offset(distance)
-	    bisectors = offset_bisectors(distance)
-	    offsets = bisectors.each_cons(2).to_a
+	    bisector_pairs = if closed?
+		bisector_edges = offset_bisectors(distance)
+		bisector_edges.push(bisector_edges.first).each_cons(2)
+	    else
+		offset_bisectors(distance).each_cons(2)
+	    end
 
 	    # Create the offset edges and then wrap them in Hashes so the edges
 	    #  can be altered while walking the array
-	    active_edges = edges.zip(offsets).map do |e,offset|
-		offset = Edge.new(e.first+offset.first.vector, e.last+offset.last.vector)
+	    active_edges = edges.zip(bisector_pairs).map do |e,offset|
+		offset_edge = Edge.new(e.first+offset.first.vector, e.last+offset.last.vector)
 
 		# Skip zero-length edges
-		{:edge => (offset.first == offset.last) ? nil : offset}
+		{:edge => (offset_edge.first == offset_edge.last) ? nil : offset_edge}
 	    end
 
 	    # Walk the array and handle any intersections
@@ -143,36 +216,69 @@ also like a {Path} in that it isn't necessarily closed.
 
 	# Rightset the receiver by the specified distance
 	# @param [Number] distance	The distance to offset by
-	# @return [Polygon] A new {Polygon} rightset by the given distance
+	# @return [Polyline] A new {Polyline} rightset by the given distance
 	def rightset(distance)
 	    offset(-distance)
 	end
 
 	private
 
-	# @group Helpers for offset()
-
-	# Vertex bisectors suitable for offsetting
-	# @param [Number] length    The distance to offset by
-	# @return [Array<Edge>]	{Edge}s representing the bisectors
-	def offset_bisectors(length)
-	    vectors = edges.map {|e| e.direction }
+	# Generate bisectors and k values with an optional mapping block
+	# @note If the {Polyline} isn't closed (the normal case), then the first and
+	#   last vertices will be given bisectors that are perpendicular to themselves.
+	# @return [Array<Vector>]   the unit {Vector}s representing the angle bisector of each vertex
+	def bisector_map
 	    winding = 0
-	    sums = vectors.unshift(vectors.first).push(vectors.last).each_cons(2).map do |v1,v2|
+	    tangent_loop.each_cons(2).map do |v1,v2|
 		k = v1[0]*v2[1] - v1[1]*v2[0]	# z-component of v1 x v2
 		winding += k
 		if v1 == v2			# collinear, same direction?
-		    Vector[-v1[1], v1[0]]
+		    bisector = Vector[-v1[1], v1[0]]
+		    block_given? ? (bisector * yield(bisector, 1)) : bisector
 		elsif 0 == k			# collinear, reverse direction
 		    nil
 		else
-		    by = (v2[1] - v1[1])/k
-		    v = (0 == v1[1]) ? v2 : v1
-		    Vector[(v[0]*by - 1)/v[1], by]
+		    bisector_y = (v2[1] - v1[1])/k
+
+		    # If v1 or v2 happens to be horizontal, then the other one must be used when calculating
+		    #  the x-component of the bisector (to avoid a divide by zero). But, comparing floats
+		    #  with zero is problematic, so use the one with the largest y-component instead checking
+		    #  for a y-component equal to zero.
+		    v = (v2[1].abs > v1[1].abs) ? v2 : v1
+
+		    bisector = Vector[(v[0]*bisector_y - 1)/v[1], bisector_y]
+		    block_given? ? (bisector * yield(bisector, k)) : bisector
 		end
 	    end
+	end
 
-	    vertices.zip(sums).map {|v,b| b ? Edge.new(v, v+(b * length)) : nil}
+	# @group Helpers for offset()
+
+	# Vertex bisectors suitable for offsetting
+	# @param [Number] length    The distance to offset by. Positive generates left offset bisectors, negative generates right offset bisectors
+	# @return [Array<Edge>]	{Edge}s representing the bisectors
+	def offset_bisectors(length)
+	    vertices.zip(left_bisectors).map {|v,b| b ? Edge.new(v, v+(b * length)) : nil}
+	end
+
+	# Generate the tangents and fake a circular buffer while accounting for closedness
+	# @return [Array<Vector>]   the tangents
+	def tangent_loop
+	    edges.map {|e| e.direction }.tap do |tangents|
+		# Generating a bisector for each vertex requires an edge on both sides of each vertex.
+		# Obviously, the first and last vertices each have only a single adjacent edge, unless the
+		# Polyline happens to be closed (like a Polygon). When not closed, duplicate the
+		# first and last direction vectors to fake the adjacent edges. This causes the first and last
+		# edges to have bisectors that are perpendicular to themselves.
+		if closed?
+		    # Prepend the last direction vector so that the last edge can be used to find the bisector for the first vertex
+		    tangents.unshift tangents.last
+		else
+		    # Duplicate the first and last direction vectors to compensate for not having edges adjacent to the first and last vertices
+		    tangents.unshift(tangents.first)
+		    tangents.push(tangents.last)
+		end
+	    end
 	end
 
 	# Find the next edge that intersects with e, starting at index i