perfect-shape 0.1.1 → 0.3.1

data/lib/perfect_shape/arc.rb

@@ -143,44 +143,58 @@ module PerfectShape
     # @return {@code true} if the point lies within the bound of
     # the arc, {@code false} if the point lies outside of the
     # arc's bounds.
-    def contain?(x_or_point, y = nil)
+    def contain?(x_or_point, y = nil, outline: false, distance_tolerance: 0)
       x, y = normalize_point(x_or_point, y)
       return unless x && y
-      # Normalize the coordinates compared to the ellipse
-      # having a center at 0,0 and a radius of 0.5.
-      ellw = width
-      return false if (ellw <= 0.0)
-      normx = (x - self.x) / ellw - 0.5
-      ellh = height
-      return false if (ellh <= 0.0)
-      normy = (y - self.y) / ellh - 0.5
-      dist_sq = (normx * normx) + (normy * normy)
-      return false if (dist_sq >= 0.25)
-      ang_ext = self.extent.abs
-      return true if (ang_ext >= 360.0)
-      inarc = contain_angle?(-1*Math.radians_to_degrees(Math.atan2(normy, normx)))
-      
-      return inarc if type == :pie
-      # CHORD and OPEN behave the same way
-      if inarc
-        return true if ang_ext >= 180.0
-        # point must be outside the "pie triangle"
+      if outline
+        if type == :pie && x == center_x && y == center_y
+          true
+        else
+          distance_tolerance = BigDecimal(distance_tolerance.to_s)
+          outside_inside_radius_difference = BigDecimal('0.001') + distance_tolerance * 2.0
+          outside_radius_difference = inside_radius_difference = outside_inside_radius_difference / 2.0
+          outside_shape = Arc.new(type: type, center_x: center_x, center_y: center_y, radius_x: radius_x + outside_radius_difference, radius_y: radius_y + outside_radius_difference, start: start, extent: extent)
+          inside_shape = Arc.new(type: type, center_x: center_x, center_y: center_y, radius_x: radius_x - inside_radius_difference, radius_y: radius_y - inside_radius_difference, start: start, extent: extent)
+          outside_shape.contain?(x, y, outline: false) and
+            !inside_shape.contain?(x, y, outline: false)
+        end
       else
-        return false if ang_ext <= 180.0
-        # point must be inside the "pie triangle"
+        # Normalize the coordinates compared to the ellipse
+        # having a center at 0,0 and a radius of 0.5.
+        ellw = width
+        return false if (ellw <= 0.0)
+        normx = (x - self.x) / ellw - 0.5
+        ellh = height
+        return false if (ellh <= 0.0)
+        normy = (y - self.y) / ellh - 0.5
+        dist_sq = (normx * normx) + (normy * normy)
+        return false if (dist_sq >= 0.25)
+        ang_ext = self.extent.abs
+        return true if (ang_ext >= 360.0)
+        inarc = contain_angle?(-1*Math.radians_to_degrees(Math.atan2(normy, normx)))
+        
+        return inarc if type == :pie
+        # CHORD and OPEN behave the same way
+        if inarc
+          return true if ang_ext >= 180.0
+          # point must be outside the "pie triangle"
+        else
+          return false if ang_ext <= 180.0
+          # point must be inside the "pie triangle"
+        end
+        
+        # The point is inside the pie triangle iff it is on the same
+        # side of the line connecting the ends of the arc as the center.
+        angle = Math.degrees_to_radians(-start)
+        x1 = Math.cos(angle)
+        y1 = Math.sin(angle)
+        angle += Math.degrees_to_radians(-extent)
+        x2 = Math.cos(angle)
+        y2 = Math.sin(angle)
+        inside = (Line.relative_counterclockwise(x1, y1, x2, y2, 2*normx, 2*normy) *
+                          Line.relative_counterclockwise(x1, y1, x2, y2, 0, 0) >= 0)
+        inarc ? !inside : inside
       end
-      
-      # The point is inside the pie triangle iff it is on the same
-      # side of the line connecting the ends of the arc as the center.
-      angle = Math.degrees_to_radians(-start)
-      x1 = Math.cos(angle)
-      y1 = Math.sin(angle)
-      angle += Math.degrees_to_radians(-extent)
-      x2 = Math.cos(angle)
-      y2 = Math.sin(angle)
-      inside = (Line.relative_counterclockwise(x1, y1, x2, y2, 2*normx, 2*normy) *
-                        Line.relative_counterclockwise(x1, y1, x2, y2, 0, 0) >= 0)
-      inarc ? !inside : inside
     end
     
     # Determines whether or not the specified angle is within the

data/lib/perfect_shape/composite_shape.rb

@@ -0,0 +1,72 @@
+# Copyright (c) 2021 Andy Maleh
+#
+# 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.
+
+require 'perfect_shape/shape'
+require 'perfect_shape/point'
+require 'perfect_shape/line'
+require 'perfect_shape/quadratic_bezier_curve'
+require 'perfect_shape/cubic_bezier_curve'
+require 'perfect_shape/multi_point'
+
+module PerfectShape
+  # A composite of multiple shapes
+  class CompositeShape < Shape
+    include Equalizer.new(:shapes)
+    
+    attr_accessor :shapes
+    
+    # Constructs from multiple shapes
+    def initialize(shapes: [])
+      self.shapes = shapes
+    end
+    
+    def min_x
+      shapes.map(&:min_x).min
+    end
+    
+    def min_y
+      shapes.map(&:min_y).min
+    end
+    
+    def max_x
+      shapes.map(&:max_x).max
+    end
+    
+    def max_y
+      shapes.map(&:max_y).max
+    end
+    
+    # Checks if composite shape contains point (two-number Array or x, y args)
+    # by comparing against all shapes it consists of
+    #
+    # @param x The X coordinate of the point to test.
+    # @param y The Y coordinate of the point to test.
+    #
+    # @return true if the point lies within the bound of
+    # the composite shape or false if the point lies outside of the
+    # path's bounds.
+    def contain?(x_or_point, y = nil)
+      x, y = normalize_point(x_or_point, y)
+      return unless x && y
+      shapes.any? {|shape| shape.contain?(x, y) }
+    end
+  end
+end

data/lib/perfect_shape/cubic_bezier_curve.rb

@@ -0,0 +1,120 @@
+# Copyright (c) 2021 Andy Maleh
+#
+# 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.
+
+require 'perfect_shape/shape'
+require 'perfect_shape/multi_point'
+
+module PerfectShape
+  # Mostly ported from java.awt.geom: https://docs.oracle.com/javase/8/docs/api/java/awt/geom/QuadCurve2D.html
+  class CubicBezierCurve < Shape
+    class << self
+      # Calculates the number of times the cubic bézier curve from (x1,y1) to (x2,y2)
+      # crosses the ray extending to the right from (x,y).
+      # If the point lies on a part of the curve,
+      # then no crossings are counted for that intersection.
+      # the level parameter should be 0 at the top-level call and will count
+      # up for each recursion level to prevent infinite recursion
+      # +1 is added for each crossing where the Y coordinate is increasing
+      # -1 is added for each crossing where the Y coordinate is decreasing
+      def point_crossings(x1, y1, xc1, yc1, xc2, yc2, x2, y2, px, py, level = 0)
+        return 0 if (py <  y1 && py <  yc1 && py <  yc2 && py <  y2)
+        return 0 if (py >= y1 && py >= yc1 && py >= yc2 && py >= y2)
+        # Note y1 could equal yc1...
+        return 0 if (px >= x1 && px >= xc1 && px >= xc2 && px >= x2)
+        if (px <  x1 && px <  xc1 && px <  xc2 && px <  x2)
+          if (py >= y1)
+            return 1 if (py < y2)
+          else
+            # py < y1
+            return -1 if (py >= y2)
+          end
+          # py outside of y12 range, and/or y1==yc1
+          return 0
+        end
+        # double precision only has 52 bits of mantissa
+        return PerfectShape::Line.point_crossings(x1, y1, x2, y2, px, py) if (level > 52)
+        xmid = BigDecimal((xc1 + xc2).to_s) / 2;
+        ymid = BigDecimal((yc1 + yc2).to_s) / 2;
+        xc1 = BigDecimal((x1 + xc1).to_s) / 2;
+        yc1 = BigDecimal((y1 + yc1).to_s) / 2;
+        xc2 = BigDecimal((xc2 + x2).to_s) / 2;
+        yc2 = BigDecimal((yc2 + y2).to_s) / 2;
+        xc1m = BigDecimal((xc1 + xmid).to_s) / 2;
+        yc1m = BigDecimal((yc1 + ymid).to_s) / 2;
+        xmc1 = BigDecimal((xmid + xc2).to_s) / 2;
+        ymc1 = BigDecimal((ymid + yc2).to_s) / 2;
+        xmid = BigDecimal((xc1m + xmc1).to_s) / 2;
+        ymid = BigDecimal((yc1m + ymc1).to_s) / 2;
+        # [xy]mid are NaN if any of [xy]c0m or [xy]mc1 are NaN
+        # [xy]c0m or [xy]mc1 are NaN if any of [xy][c][01] are NaN
+        # These values are also NaN if opposing infinities are added
+        return 0 if (xmid.nan? || ymid.nan?)
+        point_crossings(x1, y1, xc1, yc1, xc1m, yc1m, xmid, ymid, px, py, level+1) +
+          point_crossings(xmid, ymid, xmc1, ymc1, xc2, yc2, x2, y2, px, py, level+1)
+      end
+    end
+    
+    include MultiPoint
+    include Equalizer.new(:points)
+    
+    # Checks if cubic bézier curve contains point (two-number Array or x, y args)
+    #
+    # @param x The X coordinate of the point to test.
+    # @param y The Y coordinate of the point to test.
+    #
+    # @return {@code true} if the point lies within the bound of
+    # the cubic bézier curve, {@code false} if the point lies outside of the
+    # cubic bézier curve's bounds.
+    def contain?(x_or_point, y = nil)
+      x, y = normalize_point(x_or_point, y)
+      return unless x && y
+      
+      # Either x or y was infinite or NaN.
+      # A NaN always produces a negative response to any test
+      # and Infinity values cannot be "inside" any path so
+      # they should return false as well.
+      return false if (!(x * 0.0 + y * 0.0 == 0.0))
+      # We count the "Y" crossings to determine if the point is
+      # inside the curve bounded by its closing line.
+      x1 = points[0][0]
+      y1 = points[0][1]
+      x2 = points[3][0]
+      y2 = points[3][1]
+      line = PerfectShape::Line.new(points: [[x1, y1], [x2, y2]])
+      crossings = line.point_crossings(x, y) + point_crossings(x, y);
+      (crossings & 1) == 1
+    end
+    
+    # Calculates the number of times the cubic bézier curve
+    # crosses the ray extending to the right from (x,y).
+    # If the point lies on a part of the curve,
+    # then no crossings are counted for that intersection.
+    # the level parameter should be 0 at the top-level call and will count
+    # up for each recursion level to prevent infinite recursion
+    # +1 is added for each crossing where the Y coordinate is increasing
+    # -1 is added for each crossing where the Y coordinate is decreasing
+    def point_crossings(x_or_point, y = nil, level = 0)
+      x, y = normalize_point(x_or_point, y)
+      return unless x && y
+      CubicBezierCurve.point_crossings(points[0][0], points[0][1], points[1][0], points[1][1], points[2][0], points[2][1], points[3][0], points[3][1], x, y, level)
+    end
+  end
+end

data/lib/perfect_shape/ellipse.rb

@@ -63,17 +63,21 @@ module PerfectShape
     # @return {@code true} if the point lies within the bound of
     # the ellipse, {@code false} if the point lies outside of the
     # ellipse's bounds.
-    def contain?(x_or_point, y = nil)
+    def contain?(x_or_point, y = nil, outline: false, distance_tolerance: 0)
       # This is implemented again even though super would have just worked to have an optimized algorithm for Ellipse.
       x, y = normalize_point(x_or_point, y)
       return unless x && y
-      ellw = self.width
-      return false if ellw <= 0.0
-      normx = (x - self.x) / ellw - 0.5
-      ellh = self.height
-      return false if ellh <= 0.0
-      normy = (y - self.y) / ellh - 0.5
-      (normx * normx + normy * normy) < 0.25
+      if outline
+        super(x, y, outline: true, distance_tolerance: distance_tolerance)
+      else
+        ellw = self.width
+        return false if ellw <= 0.0
+        normx = (x - self.x) / ellw - 0.5
+        ellh = self.height
+        return false if ellh <= 0.0
+        normy = (y - self.y) / ellh - 0.5
+        (normx * normx + normy * normy) < 0.25
+      end
     end
   end
 end

data/lib/perfect_shape/line.rb

@@ -189,14 +189,14 @@ module PerfectShape
       # +1 is returned for a crossing where the Y coordinate is increasing
       # -1 is returned for a crossing where the Y coordinate is decreasing
       def point_crossings(x1, y1, x2, y2, px, py)
-        return BigDecimal('0') if (py <  y1 && py <  y2)
-        return BigDecimal('0') if (py >= y1 && py >= y2)
+        return 0 if (py <  y1 && py <  y2)
+        return 0 if (py >= y1 && py >= y2)
         # assert(y1 != y2);
-        return BigDecimal('0') if (px >= x1 && px >= x2)
+        return 0 if (px >= x1 && px >= x2)
         return ((y1 < y2) ? 1 : -1) if (px <  x1 && px <  x2)
         xintercept = x1 + (py - y1) * (x2 - x1) / (y2 - y1);
-        return BigDecimal('0') if (px >= xintercept)
-        (y1 < y2) ? BigDecimal('1') : BigDecimal('-1')
+        return 0 if (px >= xintercept)
+        (y1 < y2) ? 1 : -1
       end
     end
     
@@ -207,16 +207,16 @@ module PerfectShape
     #
     # @param x The X coordinate of the point to test.
     # @param y The Y coordinate of the point to test.
-    # @param distance The distance from line to tolerate (0 by default)
+    # @param distance_tolerance The distance from line to tolerate (0 by default)
     #
     # @return {@code true} if the point lies within the bound of
     # the line, {@code false} if the point lies outside of the
     # line's bounds.
-    def contain?(x_or_point, y = nil, distance: 0)
+    def contain?(x_or_point, y = nil, outline: false, distance_tolerance: 0)
       x, y = normalize_point(x_or_point, y)
       return unless x && y
-      distance = BigDecimal(distance.to_s)
-      point_segment_distance(x, y) <= distance
+      distance_tolerance = BigDecimal(distance_tolerance.to_s)
+      point_segment_distance(x, y) <= distance_tolerance
     end
     
     def point_segment_distance(x_or_point, y = nil)

data/lib/perfect_shape/path.rb

@@ -23,6 +23,7 @@ require 'perfect_shape/shape'
 require 'perfect_shape/point'
 require 'perfect_shape/line'
 require 'perfect_shape/quadratic_bezier_curve'
+require 'perfect_shape/cubic_bezier_curve'
 require 'perfect_shape/multi_point'
 
 module PerfectShape
@@ -31,7 +32,10 @@ module PerfectShape
     include MultiPoint
     include Equalizer.new(:shapes, :closed, :winding_rule)
     
-    SHAPE_TYPES = [Array, Point, Line]
+    # Available class types for path shapes
+    SHAPE_TYPES = [Array, PerfectShape::Point, PerfectShape::Line, PerfectShape::QuadraticBezierCurve, PerfectShape::CubicBezierCurve]
+    
+    # Available winding rules
     WINDING_RULES = [:wind_non_zero, :wind_even_odd]
     
     attr_reader :winding_rule
@@ -39,8 +43,9 @@ module PerfectShape
     alias closed? closed
     
     # Constructs Path with winding rule, closed status, and shapes (must always start with PerfectShape::Point or Array of [x,y] coordinates)
-    # Shape class types can be any of SHAPE_TYPES: Array (x,y coordinates), PerfectShape::Point, or PerfectShape::Line
+    # Shape class types can be any of SHAPE_TYPES: Array (x,y coordinates), PerfectShape::Point, PerfectShape::Line, PerfectShape::QuadraticBezierCurve, or PerfectShape::CubicBezierCurve
     # winding_rule can be any of WINDING_RULES: :wind_non_zero (default) or :wind_even_odd
+    # closed can be true or false
     def initialize(shapes: [], closed: false, winding_rule: :wind_non_zero)
       self.closed = closed
       self.winding_rule = winding_rule
@@ -61,7 +66,10 @@ module PerfectShape
           shape.points.each do |point|
             the_points << point.to_a
           end
-#         when CubicBezierCurve # TODO
+        when CubicBezierCurve
+          shape.points.each do |point|
+            the_points << point.to_a
+          end
         end
       end
       the_points << @shapes.first.to_a if closed?
@@ -83,7 +91,8 @@ module PerfectShape
           :line_to
         when QuadraticBezierCurve
           :quad_to
-#         when CubicBezierCurve # TODO
+        when CubicBezierCurve
+          :cubic_to
         end
       end
       the_drawing_shapes << :close if closed?
@@ -102,8 +111,8 @@ module PerfectShape
     # @param x The X coordinate of the point to test.
     # @param y The Y coordinate of the point to test.
     #
-    # @return {@code true} if the point lies within the bound of
-    # the path, {@code false} if the point lies outside of the
+    # @return true if the point lies within the bound of
+    # the path or false if the point lies outside of the
     # path's bounds.
     def contain?(x_or_point, y = nil)
       x, y = normalize_point(x_or_point, y)
@@ -113,7 +122,7 @@ module PerfectShape
         # Here we know that both x and y are finite.
         return false if shapes.count < 2
         mask = winding_rule == :wind_non_zero ? -1 : 1
-        (point_crossings(x, y).to_i & mask) != 0
+        (point_crossings(x, y) & mask) != 0
       else
         # Either x or y was infinite or NaN.
         # A NaN always produces a negative response to any test
@@ -137,67 +146,71 @@ module PerfectShape
     def point_crossings(x_or_point, y = nil)
       x, y = normalize_point(x_or_point, y)
       return unless x && y
-      return BigDecimal('0') if shapes.count == 0
+      return 0 if shapes.count == 0
       movx = movy = curx = cury = endx = endy = 0
       coords = points.flatten
       curx = movx = coords[0]
       cury = movy = coords[1]
-      crossings = BigDecimal('0')
-      ci = BigDecimal('2')
+      crossings = 0
+      ci = 2
       1.upto(shapes.count - 1).each do |i|
-          case drawing_types[i]
-          when :move_to
-            if cury != movy
-              line = PerfectShape::Line.new(points: [[curx, cury], [movx, movy]])
-              crossings += line.point_crossings(x, y)
-            end
-            movx = curx = coords[ci]
-            ci += 1
-            movy = cury = coords[ci]
-            ci += 1
-          when :line_to
-            endx = coords[ci]
-            ci += 1
-            endy = coords[ci]
-            ci += 1
-            line = PerfectShape::Line.new(points: [[curx, cury], [endx, endy]])
+        case drawing_types[i]
+        when :move_to
+          if cury != movy
+            line = PerfectShape::Line.new(points: [[curx, cury], [movx, movy]])
             crossings += line.point_crossings(x, y)
-            curx = endx;
-            cury = endy;
-          when :quad_to
-            quad_ctrlx = coords[ci]
-            ci += 1
-            quad_ctrly = coords[ci]
-            ci += 1
-            endx = coords[ci]
-            ci += 1
-            endy = coords[ci]
-            ci += 1
-            quad = PerfectShape::QuadraticBezierCurve.new(points: [[curx, cury], [quad_ctrlx, quad_ctrly], [endx, endy]])
-            crossings += quad.point_crossings(x, y, 0)
-            curx = endx;
-            cury = endy;
-#           when :cubic_to # TODO
-#             crossings +=
-#                 Curve.point_crossings_for_cubic(x, y,
-#                                              curx, cury,
-#                                              coords[ci++],
-#                                              coords[ci++],
-#                                              coords[ci++],
-#                                              coords[ci++],
-#                                              endx = coords[ci++],
-#                                              endy = coords[ci++],
-#                                              0);
-#             curx = endx;
-#             cury = endy;
-          when :close
-            if cury != movy
-              line = PerfectShape::Line.new(points: [[curx, cury], [movx, movy]])
-              crossings += line.point_crossings(x, y)
-            end
-            curx = movx
-            cury = movy
           end
+          movx = curx = coords[ci]
+          ci += 1
+          movy = cury = coords[ci]
+          ci += 1
+        when :line_to
+          endx = coords[ci]
+          ci += 1
+          endy = coords[ci]
+          ci += 1
+          line = PerfectShape::Line.new(points: [[curx, cury], [endx, endy]])
+          crossings += line.point_crossings(x, y)
+          curx = endx;
+          cury = endy;
+        when :quad_to
+          quad_ctrlx = coords[ci]
+          ci += 1
+          quad_ctrly = coords[ci]
+          ci += 1
+          endx = coords[ci]
+          ci += 1
+          endy = coords[ci]
+          ci += 1
+          quad = PerfectShape::QuadraticBezierCurve.new(points: [[curx, cury], [quad_ctrlx, quad_ctrly], [endx, endy]])
+          crossings += quad.point_crossings(x, y)
+          curx = endx;
+          cury = endy;
+        when :cubic_to
+          cubic_ctrl1x = coords[ci]
+          ci += 1
+          cubic_ctrl1y = coords[ci]
+          ci += 1
+          cubic_ctrl2x = coords[ci]
+          ci += 1
+          cubic_ctrl2y = coords[ci]
+          ci += 1
+          endx = coords[ci]
+          ci += 1
+          endy = coords[ci]
+          ci += 1
+          cubic = PerfectShape::CubicBezierCurve.new(points: [[curx, cury], [cubic_ctrl1x, cubic_ctrl1y], [cubic_ctrl2x, cubic_ctrl2y], [endx, endy]])
+          crossings += cubic.point_crossings(x, y)
+          curx = endx;
+          cury = endy;
+        when :close
+          if cury != movy
+            line = PerfectShape::Line.new(points: [[curx, cury], [movx, movy]])
+            crossings += line.point_crossings(x, y)
+          end
+          curx = movx
+          cury = movy
+        end
       end
       if cury != movy
         line = PerfectShape::Line.new(points: [[curx, cury], [movx, movy]])

data/lib/perfect_shape/point.rb

@@ -63,15 +63,15 @@ module PerfectShape
     #
     # @param x The X coordinate of the point to test.
     # @param y The Y coordinate of the point to test.
-    # @param distance The distance from point to tolerate (0 by default)
+    # @param distance_tolerance The distance from point to tolerate (0 by default)
     #
     # @return {@code true} if the point is close enough within distance tolerance,
     # {@code false} if the point is too far.
-    def contain?(x_or_point, y = nil, distance: 0)
+    def contain?(x_or_point, y = nil, outline: false, distance_tolerance: 0)
       x, y = normalize_point(x_or_point, y)
       return unless x && y
-      distance = BigDecimal(distance.to_s)
-      point_distance(x, y) <= distance
+      distance_tolerance = BigDecimal(distance_tolerance.to_s)
+      point_distance(x, y) <= distance_tolerance
     end
     
     def point_distance(x_or_point, y = nil)