sevgi-geometry 0.73.2 → 0.93.1

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Geometry
+    # Generated superclass for Triangle.
+    # @api private
+    TriangleBase = Element.lined(3)
+    private_constant :TriangleBase
+
+    # Closed three-sided element built from two adjacent segments.
+    class Triangle < TriangleBase
+      # Builds a triangle from two adjacent segments.
+      # @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
+      def self.[](segment_a, segment_b, position: Origin)
+        a, b = Tuples[Segment, segment_a, segment_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)]
+      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.closing_length(a, b, angle_between)
+        ::Math.sqrt((a.length ** 2) + (b.length ** 2) - (2 * a.length * b.length * F.cos(angle_between)))
+      end
+
+      private_class_method :closing_angle, :closing_length, :closing_segment
+    end
+  end
+end

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

@@ -3,10 +3,20 @@
 module Sevgi
   module Geometry
     class Equation
+      # Base class for linear equations.
       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
 
+          # Creates a diagonal linear equation.
+          # @param slope [Numeric] line slope
+          # @param intercept [Numeric] y-intercept
+          # @return [void]
           def initialize(slope:, intercept:)
             super()
 
@@ -14,20 +24,57 @@ module Sevgi
             @intercept = intercept.to_f
           end
 
+          # Returns an equation rounded to precision.
+          # @param precision [Integer, nil] decimal precision, or nil for the current function default
+          # @return [Sevgi::Geometry::Equation::Linear::Diagonal]
           def approx(precision = nil)
             self.class.new(slope: F.approx(slope, precision), intercept: F.approx(intercept, precision))
           end
 
+          # Reports strict equation equality.
+          # @param other [Object] object to compare
+          # @return [Boolean]
           def eql?(other) = self.class == other.class && [slope, intercept] == [other.slope, other.intercept]
 
+          # Returns a hash compatible with strict equality.
+          # @return [Integer]
           def hash = [self.class, slope, intercept].hash
 
-          def left?(point) = F.gt?(point.y, y(point.x))
+          # Reports whether a point is on the left side of the line in screen coordinates.
+          # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
+          # @return [Boolean]
+          # @raise [Sevgi::Geometry::Error] when point cannot be coerced
+          def left?(point)
+            point = Tuple[Point, point]
 
-          def on?(point) = F.eq?(point.y, y(point.x))
+            F.gt?(point.y, y(point.x))
+          end
+
+          # Reports whether a point is on the line.
+          # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
+          # @return [Boolean]
+          # @raise [Sevgi::Geometry::Error] when point cannot be coerced
+          def on?(point)
+            point = Tuple[Point, point]
+
+            F.eq?(point.y, y(point.x))
+          end
+
+          # Reports whether a point is on the right side of the line in screen coordinates.
+          # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
+          # @return [Boolean]
+          # @raise [Sevgi::Geometry::Error] when point cannot be coerced
+          def right?(point)
+            point = Tuple[Point, point]
 
-          def right?(point) = F.lt?(point.y, y(point.x))
+            F.lt?(point.y, y(point.x))
+          end
 
+          # Returns a parallel equation shifted by a signed perpendicular offset.
+          # @param distance [Numeric, nil] signed perpendicular offset
+          # @param dx [Numeric, nil] explicit x translation
+          # @param dy [Numeric, nil] explicit y translation
+          # @return [Sevgi::Geometry::Equation::Linear::Diagonal]
           def shift(distance = nil, dx: nil, dy: nil)
             dx ||= 0.0
             dy ||= 0.0
@@ -40,6 +87,8 @@ module Sevgi
             Diagonal.new(slope:, intercept: intercept - (slope * dx) + dy)
           end
 
+          # Formats the equation for display.
+          # @return [String]
           def to_s
             strings = []
 
@@ -49,41 +98,132 @@ module Sevgi
             "Linear<y = #{strings.join(intercept.positive? ? " + " : " - ")}>"
           end
 
+          # Evaluates x for a y coordinate.
+          # @param y [Numeric] y coordinate
+          # @return [Float]
           def x(y) = (y - intercept) / slope
 
+          # Evaluates y for an x coordinate.
+          # @param x [Numeric] x coordinate
+          # @return [Float]
           def y(x) = (slope * x) + intercept
 
           alias == eql?
         end
 
+        # Horizontal linear equation in `y = c` form.
         class Horizontal < Diagonal
+          # Creates a horizontal equation.
+          # @param c [Numeric] y coordinate
+          # @return [void]
           def initialize(c) = super(slope: 0.0, intercept: c)
+
+          # Returns an equation rounded to precision.
+          # @param precision [Integer, nil] decimal precision, or nil for the current function default
+          # @return [Sevgi::Geometry::Equation::Linear::Horizontal]
+          def approx(precision = nil) = self.class.new(F.approx(intercept, precision))
+
+          # Returns a parallel horizontal equation shifted by offsets.
+          #
+          # A positive signed distance shifts upward in screen coordinates.
+          # @param distance [Numeric, nil] signed perpendicular offset
+          # @param dx [Numeric, nil] accepted for signature compatibility and ignored
+          # @param dy [Numeric, nil] explicit y translation
+          # @return [Sevgi::Geometry::Equation::Linear::Horizontal]
+          def shift(distance = nil, dx: nil, dy: nil)
+            _dx = dx
+
+            self.class.new(intercept + (dy || 0.0) - (distance || 0.0))
+          end
+
+          # Formats the equation for display.
+          # @return [String]
+          def to_s = "Linear<y = #{F.approx(intercept)}>"
         end
 
+        # Vertical linear equation in `x = c` form.
         class Vertical < Linear
+          # Creates a vertical equation.
+          # @param c [Numeric] x coordinate
+          # @return [void]
           def initialize(c)
             super()
 
-            @x = c
+            @x = c.to_f
           end
 
-          def left?(point) = F.lt?(point.x, x(point.y))
+          # Returns an equation rounded to precision.
+          # @param precision [Integer, nil] decimal precision, or nil for the current function default
+          # @return [Sevgi::Geometry::Equation::Linear::Vertical]
+          def approx(precision = nil) = self.class.new(F.approx(x, precision))
 
-          def on?(point) = F.eq?(point.x, x(point.y))
+          # Reports strict equation equality.
+          # @param other [Object] object to compare
+          # @return [Boolean]
+          def eql?(other) = self.class == other.class && x == other.x
 
-          def right?(point) = F.gt?(point.x, x(point.y))
+          # Returns a hash compatible with strict equality.
+          # @return [Integer]
+          def hash = [self.class, x].hash
 
+          # Reports whether a point is on the left side of the line.
+          # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
+          # @return [Boolean]
+          # @raise [Sevgi::Geometry::Error] when point cannot be coerced
+          def left?(point)
+            point = Tuple[Point, point]
+
+            F.lt?(point.x, x(point.y))
+          end
+
+          # Reports whether a point is on the line.
+          # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
+          # @return [Boolean]
+          # @raise [Sevgi::Geometry::Error] when point cannot be coerced
+          def on?(point)
+            point = Tuple[Point, point]
+
+            F.eq?(point.x, x(point.y))
+          end
+
+          # Reports whether a point is on the right side of the line.
+          # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
+          # @return [Boolean]
+          # @raise [Sevgi::Geometry::Error] when point cannot be coerced
+          def right?(point)
+            point = Tuple[Point, point]
+
+            F.gt?(point.x, x(point.y))
+          end
+
+          # Returns a parallel vertical equation shifted by offsets.
+          #
+          # A positive signed distance shifts right in screen coordinates.
+          # @param distance [Numeric, nil] signed perpendicular offset
+          # @param dx [Numeric, nil] explicit x translation
+          # @param dy [Numeric, nil] accepted for signature compatibility and ignored
+          # @return [Sevgi::Geometry::Equation::Linear::Vertical]
           def shift(distance = nil, dx: nil, dy: nil)
             _dy = dy
 
             self.class.new(x + (distance || 0.0) + (dx || 0.0))
           end
 
+          # Formats the equation for display.
+          # @return [String]
           def to_s = "Linear<x = #{F.approx(x)}>"
 
+          # Evaluates x for a y coordinate.
+          # @param _ [Numeric, nil] ignored y coordinate
+          # @return [Float]
           def x(_ = nil) = @x
 
+          # Evaluates y for an x coordinate.
+          # @param _ [Numeric, nil] ignored x coordinate
+          # @return [Float] positive infinity because a vertical line has no single y
           def y(_ = nil) = ::Float::INFINITY
+
+          alias == eql?
         end
       end
     end

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

@@ -3,13 +3,19 @@
 module Sevgi
   module Geometry
     class Equation
+      # Base class for quadratic equations.
       class Quadratic < Equation
       end
     end
 
+    # Circle equation support is not implemented yet.
     class Circle
+      # Returns the circle equation.
+      # @abstract Circle equation support is not implemented yet.
+      # @return [Sevgi::Geometry::Equation::Quadratic]
+      # @raise [Sevgi::PanicError] until circle equation support is implemented
       def equation
-        raise NotImplementedError
+        PanicError.("#{self.class}#equation must be implemented")
       end
     end
   end

data/lib/sevgi/geometry/equation.rb

@@ -2,13 +2,29 @@
 
 module Sevgi
   module Geometry
+    # Base class for geometric equations that can intersect with each other.
     class Equation
+      # Builds a non-axis-aligned linear equation.
+      # @param slope [Numeric] line slope
+      # @param intercept [Numeric] y-intercept
+      # @return [Sevgi::Geometry::Equation::Linear::Diagonal]
       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]
       def self.horizontal(const) = Linear::Horizontal.new(const)
 
+      # Builds a vertical linear equation.
+      # @param const [Numeric] x coordinate
+      # @return [Sevgi::Geometry::Equation::Linear::Vertical]
       def self.vertical(const) = Linear::Vertical.new(const)
 
+      # Intersects this equation with another equation.
+      # @param other [Sevgi::Geometry::Equation] equation to intersect with
+      # @return [Array<Sevgi::Geometry::Point>] intersection points
+      # @raise [Sevgi::Geometry::Error] when other is not an equation
+      # @raise [Sevgi::PanicError] when the equation combination is not implemented
       def intersect(other)
         Error.("Must be an equation: #{other}") unless other.is_a?(Equation)
 
@@ -20,41 +36,61 @@ module Sevgi
         in [Quadratic, Quadratic]
           quadratic_vs_quadratic(other)
         else
-          Error.("TODO")
+          PanicError.("Intersection not implemented: #{self.class} / #{other.class}")
         end
 
         Array(points)
       end
 
-      def y(_x, ...) = raise NoMethodError, "#{self.class}#y must be implemented"
+      # Evaluates y for an x coordinate.
+      # @abstract Subclasses implement equation-specific mapping.
+      # @param _x [Numeric] x coordinate
+      # @return [Float]
+      # @raise [Sevgi::PanicError] when a subclass does not implement y
+      def y(_x, ...) = PanicError.("#{self.class}#y must be implemented")
 
       private
 
       def linear_vs_linear(other)
         case [self, other]
         in [Linear::Diagonal, Linear::Diagonal]
-          y = self.y(x = (other.intercept - intercept) / (slope - other.slope))
+          diagonal_vs_diagonal(self, other)
         in [Linear::Diagonal, Linear::Vertical]
-          y = self.y(x = other.x)
+          diagonal_vs_vertical(self, other)
         in [Linear::Vertical, Linear::Diagonal]
-          y = other.y(x = self.x())
+          diagonal_vs_vertical(other, self)
         in [Linear::Vertical, Linear::Vertical]
-          x, y = ::Float::INFINITY, ::Float::INFINITY
+          nil
         end
+      end
+
+      def diagonal_vs_diagonal(left, right)
+        return nil if F.eq?(left.slope, right.slope)
+
+        x = (right.intercept - left.intercept) / (left.slope - right.slope)
+
+        Point[x, left.y(x)]
+      end
+
+      def diagonal_vs_vertical(diagonal, vertical)
+        x = vertical.x
 
-        Point[x, y]
+        Point[x, diagonal.y(x)]
       end
 
       def linear_vs_quadratic(...)
-        raise NotImplementedError
+        PanicError.("Linear/quadratic intersection must be implemented")
       end
 
       def quadratic_vs_quadratic(...)
-        raise NotImplementedError
+        PanicError.("Quadratic/quadratic intersection must be implemented")
       end
     end
 
     class Point
+      # Returns the linear equation passing through this point at an angle.
+      # @param angle [Numeric] clockwise angle in degrees
+      # @return [Sevgi::Geometry::Equation::Linear]
       def equation(angle)
         return Equation.horizontal(y) if F.zero?(angle % 180.0)
         return Equation.vertical(x) if F.zero?(angle % 90.0)
@@ -64,6 +100,8 @@ module Sevgi
     end
 
     class Line
+      # Returns the linear equation containing this line.
+      # @return [Sevgi::Geometry::Equation::Linear]
       def equation = position.equation(angle)
     end
 

data/lib/sevgi/geometry/errors.rb

@@ -8,6 +8,7 @@ module Sevgi
   end
 
   module Geometry
+    # Base error for geometry input and operation failures.
     Error = Class.new(Error)
   end
 end

data/lib/sevgi/geometry/internal.rb

@@ -2,7 +2,14 @@
 
 module Sevgi
   module Geometry
+    # Coerces array-like geometry inputs into typed tuple objects.
+    # @api private
     module Tuple
+      # Coerces an argument into the requested tuple class.
+      # @param klass [Class] tuple class such as {Point} or {Segment}
+      # @param arg [Array<Numeric>, Object] tuple instance or two-element numeric array
+      # @return [Object] tuple instance
+      # @raise [Sevgi::Geometry::Error] when arg cannot be coerced
       def self.[](klass, arg)
         case arg
         when ::Array
@@ -20,7 +27,14 @@ module Sevgi
 
     private_constant :Tuple
 
+    # Coerces multiple array-like geometry inputs into typed tuple objects.
+    # @api private
     module Tuples
+      # Coerces arguments into the requested tuple class.
+      # @param klass [Class] tuple class such as {Point} or {Segment}
+      # @param args [Array<Array<Numeric>, Object>] tuple instances or two-element numeric arrays
+      # @return [Array<Object>] tuple instances
+      # @raise [Sevgi::Geometry::Error] when any argument cannot be coerced
       def self.[](klass, *args) = args.map { Tuple[klass, it] }
     end
 

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

@@ -3,33 +3,59 @@
 module Sevgi
   module Geometry
     module Operation
+      # Alignment operation implementation.
       module Align
+        extend self
+
+        # Returns an element translated to align with another element.
+        # @param element [Sevgi::Geometry::Element] element to move
+        # @param other [Sevgi::Geometry::Element] reference element
+        # @param alignment [Symbol] one of :center, :left, :right, :top, or :bottom
+        # @return [Sevgi::Geometry::Element] translated element
+        # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when other is not a geometry element
+        # @raise [Sevgi::ArgumentError] when alignment is unknown
         def align(element, other, alignment = :center)
-          alignment(element, other, alignment).apply(element)
+          offset = alignment(element, other, alignment)
+
+          element.translate(offset.x, offset.y)
         end
 
+        # Returns the offset needed to align one element with another.
+        # @param element [Sevgi::Geometry::Element] element to move
+        # @param other [Sevgi::Geometry::Element] reference element
+        # @param alignment [Symbol] one of :center, :left, :right, :top, or :bottom
+        # @return [Sevgi::Geometry::Point] translation offset
+        # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when other is not a geometry element
+        # @raise [Sevgi::ArgumentError] when alignment is unknown
         def alignment(element, other, alignment = :center)
+          OperationInapplicableError.("Not a Geometric Element: #{other}") unless other.is_a?(Element)
+
           this, that = element.box, other.box
 
           case alignment
           when :center
-            Translation[(this.width - that.width) / 2.0, (this.height - that.height) / 2.0]
+            Point[
+              that.position.x + ((that.width - this.width) / 2.0) - this.position.x,
+              that.position.y + ((that.height - this.height) / 2.0) - this.position.y
+            ]
           when :left
-            Translation[this.ne.x - that.ne.x, 0]
+            Point[that.position.x - this.position.x, 0]
           when :right
-            Translation[this.sw.x - that.sw.x, 0]
+            Point[(that.position.x + that.width) - (this.position.x + this.width), 0]
           when :top
-            Translation[0, this.ne.y - that.ne.y]
+            Point[0, that.position.y - this.position.y]
           when :bottom
-            Translation[0, this.sw.y - that.sw.y]
+            Point[0, (that.position.y + that.height) - (this.position.y + this.height)]
           else
             ArgumentError.("No such type of alignment: #{alignment}")
           end
         end
 
-        def applicable?(element)
-          Translation.applicable?(element)
-        end
+        # Reports whether the alignment handler can operate on an element.
+        # @api private
+        # @param element [Object] candidate element
+        # @return [Boolean]
+        def applicable?(element) = element.respond_to?(:translate)
       end
 
       register(Align, :align, :alignment)

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

@@ -3,13 +3,27 @@
 module Sevgi
   module Geometry
     module Operation
+      # Sweep operation implementation.
       module Sweep
         extend self
 
+        # Default maximum number of sweep iterations.
         LIMIT = 1_000
 
-        def sweep(element, initial:, direction:, step:, limit: LIMIT, &block)
-          equation = Tuple[Point, initial].equation(direction)
+        # Sweeps parallel lines across an element in both directions.
+        # @param element [Sevgi::Geometry::Element] element to intersect
+        # @param initial [Sevgi::Geometry::Point, Array<Numeric>] point on the initial sweep line
+        # @param angle [Numeric] clockwise sweep line angle in degrees
+        # @param step [Numeric] signed distance between sweep lines
+        # @param limit [Integer] maximum iterations per direction
+        # @yield [lines] optional hook receiving the generated lines
+        # @yieldparam lines [Array<Sevgi::Geometry::Line>] generated sweep lines
+        # @yieldreturn [void]
+        # @return [Array<Sevgi::Geometry::Line>] generated sweep lines
+        # @raise [Sevgi::Geometry::Error] when initial cannot be coerced
+        # @raise [Sevgi::Geometry::Operation::OperationError] when iteration reaches the limit
+        def sweep(element, initial:, angle:, step:, limit: LIMIT, &block)
+          equation = Tuple[Point, initial].equation(angle)
 
           [
             *unisweep(element, equation.shift(-step), -step, limit:).reverse,
@@ -19,16 +33,35 @@ module Sevgi
           end
         end
 
-        def sweep!(element, initial:, direction:, step:, limit: LIMIT, &block)
-          sweep(element, initial:, direction:, step:, limit:) do |lines|
+        # Sweeps parallel lines and requires at least one result.
+        # @param element [Sevgi::Geometry::Element] element to intersect
+        # @param initial [Sevgi::Geometry::Point, Array<Numeric>] point on the initial sweep line
+        # @param angle [Numeric] clockwise sweep line angle in degrees
+        # @param step [Numeric] signed distance between sweep lines
+        # @param limit [Integer] maximum iterations per direction
+        # @yield [lines] optional hook receiving the generated lines
+        # @yieldparam lines [Array<Sevgi::Geometry::Line>] generated sweep lines
+        # @yieldreturn [void]
+        # @return [Array<Sevgi::Geometry::Line>] generated sweep lines
+        # @raise [Sevgi::Geometry::Error] when initial cannot be coerced
+        # @raise [Sevgi::Geometry::Operation::OperationError] when no lines are found or iteration reaches the limit
+        def sweep!(element, initial:, angle:, step:, limit: LIMIT, &block)
+          sweep(element, initial:, angle:, step:, limit:) do |lines|
             if lines.empty?
-              OperationError.("No lines found [initial: #{initial}, direction: #{direction} step: #{step}]")
+              OperationError.("No lines found [initial: #{initial}, angle: #{angle} step: #{step}]")
             end
 
             yield(lines) if block
           end
         end
 
+        # Sweeps parallel lines in one signed direction from an equation.
+        # @param element [Sevgi::Geometry::Element] element to intersect
+        # @param equation [Sevgi::Geometry::Equation] initial sweep equation
+        # @param step [Numeric] signed distance between sweep lines
+        # @param limit [Integer] maximum iterations
+        # @return [Array<Sevgi::Geometry::Line>] generated sweep lines
+        # @raise [Sevgi::Geometry::Operation::OperationError] when iteration reaches the limit
         def unisweep(element, equation, step, limit: LIMIT)
           lines = []
 
@@ -46,6 +79,10 @@ module Sevgi
           OperationError.("Loop limit reached: #{limit}")
         end
 
+        # Reports whether the sweep handler can operate on an element.
+        # @api private
+        # @param element [Object] candidate element
+        # @return [Boolean]
         def applicable?(element)
           element.respond_to?(:intersection)
         end

data/lib/sevgi/geometry/operation.rb

@@ -2,12 +2,21 @@
 
 module Sevgi
   module Geometry
+    # Dispatches geometry operations to operation handler modules.
     module Operation
       extend self
 
+      # Raised when an operation starts but cannot complete.
       OperationError = Class.new(Error)
+
+      # Raised when an operation does not apply to the target element.
       OperationInapplicableError = Class.new(Error)
 
+      # Registers one or more public operation methods.
+      # @api private
+      # @param handler [Module] operation handler module
+      # @param operations [Array<Symbol>] operation method names
+      # @return [Array<Symbol>] registered operation names
       def register(handler, *operations) = operations.each { |operation| def_operation(operation, handler) }
 
       private