sevgi-geometry 0.73.2 → 0.94.0

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Geometry
+    # Generated superclass for Parallelogram.
+    # @api private
+    ParallelogramBase = Element.lined(4)
+    private_constant :ParallelogramBase
+
+    # Closed four-sided element built from horizontal and vertical segments.
+    class Parallelogram < ParallelogramBase
+      # Builds a parallelogram from adjacent horizontal and vertical segments.
+      # @param horizontal [Sevgi::Geometry::Segment, Array<Numeric>] horizontal segment
+      # @param vertical [Sevgi::Geometry::Segment, Array<Numeric>] vertical segment
+      # @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
+      # @return [Sevgi::Geometry::Parallelogram]
+      # @raise [Sevgi::Geometry::Error] when segments or position cannot be coerced
+      def self.[](horizontal, vertical, position: Origin)
+        horizontal, vertical = Tuples[Segment, horizontal, vertical]
+
+        new_by_segments(horizontal, vertical.reverse, horizontal.reverse, vertical, position:)
+      end
+
+      # Builds a parallelogram from a horizontal segment and tallness constraint.
+      # @param horizontal [Sevgi::Geometry::Segment, Array<Numeric>] horizontal segment
+      # @param tallness [Sevgi::Geometry::Polar, Array<Numeric>] target tallness as length and angle
+      # @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
+      # @return [Sevgi::Geometry::Parallelogram]
+      # @raise [Sevgi::Geometry::Error] when inputs cannot be coerced
+      def self.new_by_height(horizontal:, tallness:, position: Origin)
+        horizontal = Tuple[Segment, horizontal]
+        tallness = Tuple[Polar, tallness]
+
+        height = tallness.length - horizontal.y.abs
+        angle = tallness.angle
+        length = height / F.sin(angle)
+
+        self[horizontal, Segment[length, angle], position:]
+      end
+
+      # Builds a parallelogram from a vertical segment and wideness constraint.
+      # @param vertical [Sevgi::Geometry::Segment, Array<Numeric>] vertical segment
+      # @param wideness [Sevgi::Geometry::Polar, Array<Numeric>] target wideness as length and angle
+      # @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
+      # @return [Sevgi::Geometry::Parallelogram]
+      # @raise [Sevgi::Geometry::Error] when inputs cannot be coerced
+      def self.new_by_width(vertical:, wideness:, position: Origin)
+        vertical = Tuple[Segment, vertical]
+        wideness = Tuple[Polar, wideness]
+
+        width = wideness.length - vertical.x.abs
+        angle = wideness.angle
+        length = width / F.cos(angle)
+
+        self[Segment[length, angle], vertical, position:]
+      end
+    end
+  end
+end

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

@@ -2,7 +2,13 @@
 
 module Sevgi
   module Geometry
-    class Polygon < Element.lined
+    # Generated superclass for Polygon.
+    # @api private
+    PolygonBase = Element.lined
+    private_constant :PolygonBase
+
+    # Variable-size closed lined element.
+    class Polygon < PolygonBase
     end
   end
 end

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

@@ -2,7 +2,13 @@
 
 module Sevgi
   module Geometry
-    class Polyline < Element.lined(open: true)
+    # Generated superclass for Polyline.
+    # @api private
+    PolylineBase = Element.lined(open: true)
+    private_constant :PolylineBase
+
+    # Variable-size open lined element.
+    class Polyline < PolylineBase
     end
   end
 end

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

@@ -2,8 +2,36 @@
 
 module Sevgi
   module Geometry
-    class Rect < Element.lined(4)
-      def self.call(top_left, bottom_right)
+    # Generated superclass for Rect.
+    # @api private
+    RectBase = Element.lined(4)
+    private_constant :RectBase
+
+    # Closed four-sided rectangle aligned to the screen axes.
+    class Rect < RectBase
+      # @overload [](width, height, position: Origin)
+      #   Builds a rectangle from size and top-left position.
+      #   @param width [Numeric] rectangle width
+      #   @param height [Numeric] rectangle height
+      #   @param position [Sevgi::Geometry::Point, Array<Numeric>] top-left position
+      #   @return [Sevgi::Geometry::Rect]
+      #   @raise [Sevgi::Geometry::Error] when position cannot be coerced
+      def self.[](...) = from_size(...)
+
+      # @overload call(top_left, bottom_right)
+      #   Builds a rectangle from two opposite corners.
+      #   @param top_left [Sevgi::Geometry::Point, Array<Numeric>] top-left corner
+      #   @param bottom_right [Sevgi::Geometry::Point, Array<Numeric>] bottom-right corner
+      #   @return [Sevgi::Geometry::Rect]
+      #   @raise [Sevgi::Geometry::Error] when either point cannot be coerced
+      def self.call(...) = from_corners(...)
+
+      # Builds a rectangle from two opposite corners.
+      # @param top_left [Sevgi::Geometry::Point, Array<Numeric>] top-left corner
+      # @param bottom_right [Sevgi::Geometry::Point, Array<Numeric>] bottom-right corner
+      # @return [Sevgi::Geometry::Rect]
+      # @raise [Sevgi::Geometry::Error] when either point cannot be coerced
+      def self.from_corners(top_left, bottom_right)
         top_left, bottom_right = Tuples[Point, top_left, bottom_right]
         width = (bottom_right.x - top_left.x).abs
 
@@ -15,35 +43,87 @@ module Sevgi
         )
       end
 
-      def self.[](width, height, position: Origin)
+      # Builds a rectangle from size and top-left position.
+      # @param width [Numeric] rectangle width
+      # @param height [Numeric] rectangle height
+      # @param position [Sevgi::Geometry::Point, Array<Numeric>] top-left position
+      # @return [Sevgi::Geometry::Rect]
+      # @raise [Sevgi::Geometry::Error] when position cannot be coerced
+      def self.from_size(width, height, position: Origin)
         new_by_segments(
-          Segment.horizontal(width),
-          Segment.vertical(height),
-          Segment.horizontal!(width),
-          Segment.vertical!(height),
+          Segment.rightward(width),
+          Segment.downward(height),
+          Segment.leftward(width),
+          Segment.upward(height),
           position:
         )
       end
 
+      # Draws the rectangle into a graphics node.
+      # @param node [Object] graphics node receiving the drawing command
+      # @return [Object] graphics node command result
       def draw!(node, **) = node.rect(x: position.x, y: position.y, width: width, height: height, **)
 
+      # Returns rectangle height.
+      # @return [Float]
       def height = @height ||= segments[1].length
 
+      # Returns rectangle width.
+      # @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
     end
 
+    # Rectangle with equal width and height.
     class Square < Rect
+      # @return [Float] side length
       alias length width
 
-      def self.[](length, position: Origin) = super(length, length, position:)
+      # Builds a square from side length and top-left position.
+      # @param length [Numeric] side length
+      # @param position [Sevgi::Geometry::Point, Array<Numeric>] top-left position
+      # @return [Sevgi::Geometry::Square]
+      # @raise [Sevgi::Geometry::Error] when position cannot be coerced
+      def self.[](length, position: Origin) = from_size(length, length, position:)
     end
   end
 end

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

@@ -0,0 +1,47 @@
+# 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 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, 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)
+        Segment.(b.ending(a.ending(Origin)), Origin)
+      end
+
+      def self.cross(a, b) = (a.x * b.y) - (a.y * b.x)
+
+      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_segment, :cross, :validate!
+    end
+  end
+end

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

@@ -3,31 +3,79 @@
 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]
+          # @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.
+          # @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 +88,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 +99,134 @@ 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]
+          # @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.
+          # @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]
+          # @raise [Sevgi::Geometry::Error] when c is not a finite Numeric
           def initialize(c)
             super()
 
-            @x = c
+            @x = Real[:x, c]
           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,14 +3,23 @@
 module Sevgi
   module Geometry
     class Equation
+      # Base class for quadratic equations.
       class Quadratic < Equation
       end
     end
 
+    # Reserved circle element support.
+    # @api private
     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
+
+    private_constant :Circle
   end
 end

data/lib/sevgi/geometry/equation.rb

@@ -2,13 +2,32 @@
 
 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]
+      # @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.
+      # @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 +39,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 +103,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