sevgi-geometry 0.93.1 → 0.95.0

data/README.md

@@ -1,5 +1,37 @@
 # Sevgi Geometry
 
-Provides small geometry primitives and operations for Sevgi drawings.
+Small geometry primitives and operations for Sevgi drawings.
 
-See the root [README](../README.md) and the documentation site for usage.
+## Install
+
+```sh
+gem install sevgi-geometry
+```
+
+## Require
+
+```ruby
+require "sevgi/geometry"
+```
+
+## Example
+
+```ruby
+rect = Sevgi::Geometry::Rect[3, 5]
+rect.box.width
+```
+
+## Ruby compatibility
+
+Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4.0 and the current development Ruby from `.ruby-version`.
+
+## Native prerequisites
+
+None beyond Ruby and this gem's Ruby dependencies.
+
+## Links
+
+- Documentation: https://sevgi.roktas.dev
+- API documentation: https://www.rubydoc.info/gems/sevgi-geometry
+- Source: https://github.com/roktas/sevgi/tree/main/geometry
+- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/lib/sevgi/geometry/element.rb

@@ -19,6 +19,8 @@ module Sevgi
       #   @raise [NoMethodError] until arced elements are implemented
       def self.arced(...) = Arced.build(...)
 
+      private_class_method :arced
+
       # Core API
 
       # Returns a copy moved to a point and optional offset.
@@ -201,6 +203,11 @@ module Sevgi
 
         private_class_method :define_line_shortcuts, :define_point_shortcuts, :define_shortcuts
 
+        # Creates a lined element from a geometry-definition block.
+        # @yield evaluates point or segment definitions in the new element
+        # @yieldreturn [Object] ignored block result
+        # @return [void]
+        # @raise [Sevgi::Geometry::Error] when the block is absent or defines inconsistent geometry
         def initialize(&block)
           super()
 
@@ -210,6 +217,7 @@ module Sevgi
 
           @points ||= calculate_points_from_segments
           @segments ||= calculate_segments_from_points
+          freeze_geometry!
 
           sanitize
         end
@@ -234,11 +242,11 @@ module Sevgi
           approx.draw!(...)
         end
 
-        # Returns element points.
+        # Returns immutable element points.
         # @param approximate [Boolean] true to round points with the current function precision
-        # @return [Array<Sevgi::Geometry::Point>]
+        # @return [Array<Sevgi::Geometry::Point>] frozen point collection
         def points(approximate = false)
-          approximate ? @points.map(&:approx) : @points
+          approximate ? @points.map(&:approx).freeze : @points
         end
 
         # Returns the first point.
@@ -247,15 +255,54 @@ module Sevgi
           @position ||= points.first
         end
 
-        # Returns element segments.
+        # Returns immutable element segments.
         # @param approximate [Boolean] true to round segments with the current function precision
-        # @return [Array<Sevgi::Geometry::Segment>]
+        # @return [Array<Sevgi::Geometry::Segment>] frozen segment collection
         def segments(approximate = false)
-          approximate ? @segments.map(&:approx) : @segments
+          approximate ? @segments.map(&:approx).freeze : @segments
         end
 
         # Affinity methods
 
+        # @!parse
+        #   # Returns an element reflected across the selected axes.
+        #   # @param x [Boolean] reflect across the x-axis
+        #   # @param y [Boolean] reflect across the y-axis
+        #   # @return [Sevgi::Geometry::Element::Lined]
+        #   def reflect(x: true, y: true); end
+        #
+        #   # Returns an element rotated around the origin.
+        #   # @param a [Numeric] clockwise angle in degrees
+        #   # @return [Sevgi::Geometry::Element::Lined]
+        #   def rotate(a); end
+        #
+        #   # Returns an element scaled from the origin.
+        #   # @param sx [Numeric] x scale factor
+        #   # @param sy [Numeric, Sevgi::Undefined] y scale factor, defaulting to sx
+        #   # @return [Sevgi::Geometry::Element::Lined]
+        #   def scale(sx, sy = Undefined); end
+        #
+        #   # Returns an element skewed from the origin.
+        #   # @param ax [Numeric] x-axis skew angle in degrees
+        #   # @param ay [Numeric, Sevgi::Undefined] y-axis skew angle in degrees, defaulting to ax
+        #   # @return [Sevgi::Geometry::Element::Lined]
+        #   def skew(ax, ay = Undefined); end
+        #
+        #   # Returns an element skewed along x.
+        #   # @param a [Numeric] skew angle in degrees
+        #   # @return [Sevgi::Geometry::Element::Lined]
+        #   def skew_x(a); end
+        #
+        #   # Returns an element skewed along y.
+        #   # @param a [Numeric] skew angle in degrees
+        #   # @return [Sevgi::Geometry::Element::Lined]
+        #   def skew_y(a); end
+        #
+        #   # Returns an element translated by offset.
+        #   # @param dx [Numeric] x offset
+        #   # @param dy [Numeric, Sevgi::Undefined] y offset, defaulting to dx
+        #   # @return [Sevgi::Geometry::Element::Lined]
+        #   def translate(dx, dy = Undefined); end
         Geometry::Affinity.instance_methods.each do |transform|
           define_method(transform) do |*args, **kwargs, &block|
             self.class.new_by_points!(*points.map { it.public_send(transform, *args, **kwargs, &block) })
@@ -264,36 +311,50 @@ module Sevgi
 
         # Equality methods
 
-        # Reports strict element equality by class and approximate points.
+        # Compares element points with optional numeric precision.
+        # @param other [Object] object to compare
+        # @param precision [Integer, nil] decimal precision, or nil for the current function default
+        # @return [Boolean]
+        def eq?(other, precision: nil)
+          other.instance_of?(self.class) &&
+            points.size == other.points.size &&
+            points.zip(other.points).all? { |left, right| left.eq?(right, precision:) }
+        end
+
+        # Reports strict element equality by class and exact points.
         # @param other [Object] object to compare
         # @return [Boolean]
-        def eql?(other) = self.class == other.class && points(true) == other.points(true)
+        def eql?(other) = other.instance_of?(self.class) && points == other.points
 
         # Returns a hash compatible with strict equality.
         # @return [Integer]
-        def hash = [self.class, *points(true)].hash
+        def hash = [self.class, *points].hash
 
         alias == eql?
 
         # Interaction methods
 
-        # Returns boundary equations for all lines.
-        # @return [Array<Sevgi::Geometry::Equation::Linear>]
-        def equations = @equations ||= lines.map(&:equation)
+        # Returns immutable boundary equations for all lines.
+        # @return [Array<Sevgi::Geometry::Equation::Linear>] frozen equation collection
+        def equations = @equations ||= lines.map(&:equation).freeze
 
         # Intersects the element boundary with an equation.
+        #
+        # Boundary membership is tested on unrounded candidate points. `precision:`
+        # only rounds returned coordinates and controls duplicate collapse after
+        # membership has been accepted. When `precision` is nil, returned points use
+        # the current function precision.
         # @param equation [Sevgi::Geometry::Equation] equation to intersect with
-        # @param precision [Integer, nil] decimal precision, or nil for the current function default
+        # @param precision [Integer, nil] decimal precision for returned points, or nil for the current function default
         # @return [Array<Sevgi::Geometry::Point>] unique boundary intersection points
         # @raise [Sevgi::Geometry::Error] when equation is not an equation
         # @raise [Sevgi::PanicError] when the equation combination is not implemented
         def intersection(equation, precision: nil)
-          equations
-            .map do |candidate|
-              equation.intersect(candidate).map { |point| point.approx(precision) }.select { |point| on?(point) }
-            end
-            .flatten
-            .uniq
+          points = equations.flat_map do |candidate|
+            equation.intersect(candidate).select { |point| boundary_point?(point, precision) }
+          end
+
+          points.map { |point| point.approx(precision) }.uniq
         end
 
         # Properties
@@ -318,12 +379,15 @@ module Sevgi
         # @return [Sevgi::Geometry::Segment]
         def head = @head ||= segments.first
 
-        # Returns boundary lines derived from segments and points.
-        # @return [Array<Sevgi::Geometry::Line>]
+        # Returns immutable boundary lines derived from segments and points.
+        # @return [Array<Sevgi::Geometry::Line>] frozen line collection
         def lines
-          @lines ||= segments.zip(points[...segments.size]).map { |segment, position|
-            segment.line(position)
-          }
+          @lines ||= segments
+            .zip(points[...segments.size])
+            .map { |segment, position|
+              segment.line(position)
+            }
+            .freeze
         end
 
         # Returns the sum of segment lengths.
@@ -337,12 +401,17 @@ module Sevgi
         # Relation methods
 
         # Reports whether a point is inside or on the boundary.
+        #
+        # Open paths have no filled interior; for them this predicate is true
+        # only for points on the actual path boundary.
         # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
         # @return [Boolean]
         # @raise [Sevgi::Geometry::Error] when point cannot be coerced
         def inside?(point)
           point = Tuple[Point, point]
 
+          return on?(point) if self.class.open?
+
           on?(point) || pnpoly(points, point)
         end
 
@@ -364,6 +433,12 @@ module Sevgi
 
         private
 
+        def boundary_point?(point, precision)
+          return on?(point) if precision.nil?
+
+          F.with_precision(precision) { on?(point) }
+        end
+
         def calculate_points_from_segments
           Error.("No segments found") unless segments
 
@@ -379,6 +454,11 @@ module Sevgi
           points.each_cons(2).map { Segment.(*it) }
         end
 
+        def freeze_geometry!
+          @points = @points.dup.freeze
+          @segments = @segments.dup.freeze
+        end
+
         # rubocop:disable Metrics/MethodLength
         # https://wrfranklin.org/Research/Short_Notes/pnpoly.html
         def pnpoly(vertices, test)
@@ -418,6 +498,8 @@ module Sevgi
       # @api private
       class Arced < self
       end
+
+      private_constant :Arced
       # rubocop:enable Metrics/ClassLength
     end
 
@@ -427,9 +509,5 @@ module Sevgi
     require_relative "elements/polyline"
     require_relative "elements/rect"
     require_relative "elements/triangle"
-
-    require_relative "elements/circle"
-    require_relative "elements/curve"
-    require_relative "elements/ellipse"
   end
 end

data/lib/sevgi/geometry/elements/line.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "forwardable"
-
 module Sevgi
   module Geometry
     # Generated superclass for Line.
@@ -36,14 +34,33 @@ module Sevgi
       #   @raise [Sevgi::Geometry::Error] when either point cannot be coerced
       def self.from_points(...) = new_by_points(...)
 
-      extend Forwardable
+      # Returns the clockwise line angle in degrees.
+      # @return [Float]
+      def angle = head.angle
+
+      # Returns the ending point.
+      # @return [Sevgi::Geometry::Point]
+      def ending = points.last
+
+      # Reports whether a point is left of the line equation.
+      # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
+      # @return [Boolean]
+      # @raise [Sevgi::Geometry::Error] when point cannot be coerced
+      def left?(point) = equation.left?(point)
 
-      def_delegators :head, :length, :angle
+      # Returns the line segment length.
+      # @return [Float]
+      def length = head.length
 
-      def_delegator :points, :first, :starting
-      def_delegator :points, :last, :ending
+      # Reports whether a point is right of the line equation.
+      # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
+      # @return [Boolean]
+      # @raise [Sevgi::Geometry::Error] when point cannot be coerced
+      def right?(point) = equation.right?(point)
 
-      def_delegators :equation, :left?, :right?
+      # Returns the starting point.
+      # @return [Sevgi::Geometry::Point]
+      def starting = points.first
 
       # Draws the line into a graphics node.
       # @param node [Object] graphics node receiving the drawing command
@@ -68,8 +85,6 @@ module Sevgi
       private
 
       def within_range?(point)
-        return false if point.nan?
-
         point = point.approx
         points = [starting.approx, ending.approx]
 

data/lib/sevgi/geometry/elements/rect.rb

@@ -72,10 +72,42 @@ module Sevgi
       # @return [Float]
       def width = @width ||= segments[0].length
 
+      # @!parse
+      #   # Returns the top-left corner.
+      #   # @return [Sevgi::Geometry::Point]
+      #   def top_left; end
+      #
+      #   # Returns the top-right corner.
+      #   # @return [Sevgi::Geometry::Point]
+      #   def top_right; end
+      #
+      #   # Returns the bottom-right corner.
+      #   # @return [Sevgi::Geometry::Point]
+      #   def bottom_right; end
+      #
+      #   # Returns the bottom-left corner.
+      #   # @return [Sevgi::Geometry::Point]
+      #   def bottom_left; end
       %i[top_left top_right bottom_right bottom_left].each_with_index do |corner, i|
         define_method(corner) { points[i] }
       end
 
+      # @!parse
+      #   # Returns the top side line.
+      #   # @return [Sevgi::Geometry::Line]
+      #   def top; end
+      #
+      #   # Returns the right side line.
+      #   # @return [Sevgi::Geometry::Line]
+      #   def right; end
+      #
+      #   # Returns the bottom side line.
+      #   # @return [Sevgi::Geometry::Line]
+      #   def bottom; end
+      #
+      #   # Returns the left side line.
+      #   # @return [Sevgi::Geometry::Line]
+      #   def left; end
       %i[top right bottom left].each_with_index do |side, i|
         define_method(side) { lines[i] }
       end

data/lib/sevgi/geometry/elements/triangle.rb

@@ -7,37 +7,41 @@ module Sevgi
     TriangleBase = Element.lined(3)
     private_constant :TriangleBase
 
-    # Closed three-sided element built from two adjacent segments.
+    # Closed three-sided element built from two non-collinear adjacent segments.
     class Triangle < TriangleBase
       # Builds a triangle from two adjacent segments.
+      #
+      # The closing segment is the direct vector from the end of `segment_b`
+      # back to `position`. Segment order controls orientation; reversing the
+      # inputs returns the corresponding opposite orientation. Zero-length or
+      # collinear inputs are rejected using the current numeric precision.
       # @param segment_a [Sevgi::Geometry::Segment, Array<Numeric>] first segment
       # @param segment_b [Sevgi::Geometry::Segment, Array<Numeric>] second segment
       # @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
       # @return [Sevgi::Geometry::Triangle]
-      # @raise [Sevgi::Geometry::Error] when segments or position cannot be coerced
+      # @raise [Sevgi::Geometry::Error] when segments or position cannot be coerced, or the segments are degenerate
       def self.[](segment_a, segment_b, position: Origin)
         a, b = Tuples[Segment, segment_a, segment_b]
 
+        validate!(a, b)
         new_by_segments(a, b, closing_segment(a, b), position:)
       end
 
       def self.closing_segment(a, b)
-        b_reverse_angle = b.angle - 180.0
-        angle_between = b_reverse_angle - a.angle
-        length = closing_length(a, b, angle_between)
-
-        Segment[length, closing_angle(a, b_reverse_angle, angle_between, length)]
+        Segment.(b.ending(a.ending(Origin)), Origin)
       end
 
-      def self.closing_angle(a, b_reverse_angle, angle_between, length)
-        b_reverse_angle + F.asin(a.length * F.sin(angle_between) / length)
-      end
+      def self.cross(a, b) = (a.x * b.y) - (a.y * b.x)
 
-      def self.closing_length(a, b, angle_between)
-        ::Math.sqrt((a.length ** 2) + (b.length ** 2) - (2 * a.length * b.length * F.cos(angle_between)))
+      def self.validate!(a, b)
+        if F.zero?(a.length) ||
+            F.zero?(b.length) ||
+            F.zero?(cross(a, b))
+          Error.("Triangle segments must form a non-degenerate triangle")
+        end
       end
 
-      private_class_method :closing_angle, :closing_length, :closing_segment
+      private_class_method :closing_segment, :cross, :validate!
     end
   end
 end

data/lib/sevgi/geometry/equation/linear.rb

@@ -7,21 +7,24 @@ module Sevgi
       class Linear < Equation
         # Non-axis-aligned linear equation in `y = slope * x + intercept` form.
         class Diagonal < Linear
-          # @!attribute [r] slope
-          #   @return [Float] line slope
-          # @!attribute [r] intercept
-          #   @return [Float] y-intercept
-          attr_reader :slope, :intercept
+          # Returns the line slope.
+          # @return [Float]
+          attr_reader :slope
+
+          # Returns the y-intercept.
+          # @return [Float]
+          attr_reader :intercept
 
           # Creates a diagonal linear equation.
           # @param slope [Numeric] line slope
           # @param intercept [Numeric] y-intercept
           # @return [void]
+          # @raise [Sevgi::Geometry::Error] when a coefficient is not a finite Numeric
           def initialize(slope:, intercept:)
             super()
 
-            @slope = slope.to_f
-            @intercept = intercept.to_f
+            @slope = Real[:slope, slope]
+            @intercept = Real[:intercept, intercept]
           end
 
           # Returns an equation rounded to precision.
@@ -116,6 +119,7 @@ module Sevgi
           # Creates a horizontal equation.
           # @param c [Numeric] y coordinate
           # @return [void]
+          # @raise [Sevgi::Geometry::Error] when c is not a finite Numeric
           def initialize(c) = super(slope: 0.0, intercept: c)
 
           # Returns an equation rounded to precision.
@@ -146,10 +150,11 @@ module Sevgi
           # Creates a vertical equation.
           # @param c [Numeric] x coordinate
           # @return [void]
+          # @raise [Sevgi::Geometry::Error] when c is not a finite Numeric
           def initialize(c)
             super()
 
-            @x = c.to_f
+            @x = Real[:x, c]
           end
 
           # Returns an equation rounded to precision.

data/lib/sevgi/geometry/equation/quadratic.rb

@@ -3,12 +3,16 @@
 module Sevgi
   module Geometry
     class Equation
-      # Base class for quadratic equations.
+      # Base class reserved for future quadratic equation support.
+      # @api private
       class Quadratic < Equation
       end
+
+      private_constant :Quadratic
     end
 
-    # Circle equation support is not implemented yet.
+    # Reserved circle element support.
+    # @api private
     class Circle
       # Returns the circle equation.
       # @abstract Circle equation support is not implemented yet.
@@ -18,5 +22,7 @@ module Sevgi
         PanicError.("#{self.class}#equation must be implemented")
       end
     end
+
+    private_constant :Circle
   end
 end

data/lib/sevgi/geometry/equation.rb

@@ -8,16 +8,19 @@ module Sevgi
       # @param slope [Numeric] line slope
       # @param intercept [Numeric] y-intercept
       # @return [Sevgi::Geometry::Equation::Linear::Diagonal]
+      # @raise [Sevgi::Geometry::Error] when a coefficient is not a finite Numeric
       def self.diagonal(slope:, intercept:) = Linear::Diagonal.new(slope:, intercept:)
 
       # Builds a horizontal linear equation.
       # @param const [Numeric] y coordinate
       # @return [Sevgi::Geometry::Equation::Linear::Horizontal]
+      # @raise [Sevgi::Geometry::Error] when const is not a finite Numeric
       def self.horizontal(const) = Linear::Horizontal.new(const)
 
       # Builds a vertical linear equation.
       # @param const [Numeric] x coordinate
       # @return [Sevgi::Geometry::Equation::Linear::Vertical]
+      # @raise [Sevgi::Geometry::Error] when const is not a finite Numeric
       def self.vertical(const) = Linear::Vertical.new(const)
 
       # Intersects this equation with another equation.

data/lib/sevgi/geometry/internal.rb

@@ -2,6 +2,39 @@
 
 module Sevgi
   module Geometry
+    # Validates numeric inputs that can be represented as finite Floats.
+    # @api private
+    module Real
+      # Coerces a public numeric value to a finite Float.
+      # @param field [Symbol, String] coordinate or component name
+      # @param value [Object] value to coerce
+      # @return [Float] finite float value
+      # @raise [Sevgi::Geometry::Error] when value is not a Numeric, cannot be converted to Float, or is not finite
+      def self.[](field, value)
+        unless value.is_a?(::Numeric)
+          Error.("Geometry #{field} must be a finite Numeric: #{value.inspect}")
+        end
+
+        number = coerce(field, value)
+
+        unless number.is_a?(::Float) && number.finite?
+          Error.("Geometry #{field} must be finite: #{value.inspect}")
+        end
+
+        number
+      end
+
+      def self.coerce(field, value)
+        value.to_f
+      rescue ::StandardError => e
+        Error.("Geometry #{field} must be a finite Numeric: #{value.inspect} (#{e.message})")
+      end
+
+      private_class_method :coerce
+    end
+
+    private_constant :Real
+
     # Coerces array-like geometry inputs into typed tuple objects.
     # @api private
     module Tuple
@@ -13,8 +46,7 @@ module Sevgi
       def self.[](klass, arg)
         case arg
         when ::Array
-          Error.("Array must have 2 elements: #{arg}", arg) unless arg.size == 2
-          Error.("Must be a numeric array: #{arg}") unless arg.all?(::Numeric)
+          Error.("Array must have 2 elements: #{arg.inspect}") unless arg.size == 2
 
           klass.send(:new, *arg)
         when klass

data/lib/sevgi/geometry/operation/align.rb

@@ -59,6 +59,8 @@ module Sevgi
       end
 
       register(Align, :align, :alignment)
+
+      private_constant :Align
     end
   end
 end