sevgi-geometry 0.95.0 → 1.0.0

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

@@ -7,8 +7,52 @@ module Sevgi
     PolylineBase = Element.lined(open: true)
     private_constant :PolylineBase
 
-    # Variable-size open lined element.
+    # Variable-size open lined element with at least two points.
+    # @!method self.[](*segments, position: Origin)
+    #   Builds a polyline from ordered segments.
+    #   @param segments [Array<Sevgi::Geometry::Segment, Array<Numeric>>] ordered segments
+    #   @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
+    #   @return [Sevgi::Geometry::Polyline]
+    #   @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or do not form a polyline
+    # @!method self.call(*points)
+    #   Builds a polyline from ordered points.
+    #   @param points [Array<Sevgi::Geometry::Point, Array<Numeric>>] ordered points
+    #   @return [Sevgi::Geometry::Polyline]
+    #   @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or do not form a polyline
+    # @!method self.from_segments(*segments, position: Origin)
+    #   Builds a polyline from ordered segments.
+    #   @param segments [Array<Sevgi::Geometry::Segment, Array<Numeric>>] ordered segments
+    #   @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
+    #   @return [Sevgi::Geometry::Polyline]
+    #   @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or do not form a polyline
+    # @!method self.from_points(*points)
+    #   Builds a polyline from ordered points.
+    #   @param points [Array<Sevgi::Geometry::Point, Array<Numeric>>] ordered points
+    #   @return [Sevgi::Geometry::Polyline]
+    #   @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or do not form a polyline
+    # @!method starting
+    #   Returns the first point in the directed path.
+    #   @return [Sevgi::Geometry::Point]
+    # @!method ending
+    #   Returns the last point in the directed path.
+    #   @return [Sevgi::Geometry::Point]
+    # @!method reverse
+    #   Returns the same trace with opposite traversal.
+    #   @return [Sevgi::Geometry::Polyline]
+    # @example Pair mathematical notation with English conveniences
+    #   Sevgi::Geometry::Polyline[[2, 0], [1, 90]] == Sevgi::Geometry::Polyline.from_segments([2, 0], [1, 90])
+    #   Sevgi::Geometry::Polyline.([0, 0], [2, 0]) == Sevgi::Geometry::Polyline.from_points([0, 0], [2, 0])
+    # @example Measure and query an open path
+    #   path = Sevgi::Geometry::Polyline.([0, 0], [3, 0], [3, 4])
+    #   path.length         # => 7.0
+    #   path.on?([2, 0])    # => true
+    #   path.inside?([1, 1]) # => false
     class Polyline < PolylineBase
+      private
+
+      def validate_geometry!
+        Error.("Polyline requires at least two points") if points.size < 2
+      end
     end
   end
 end

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

@@ -7,7 +7,36 @@ module Sevgi
     RectBase = Element.lined(4)
     private_constant :RectBase
 
-    # Closed four-sided rectangle aligned to the screen axes.
+    # Closed four-sided rectangle aligned to the screen axes. Affine operations return Rect while the result remains
+    # axis-aligned and widen to {Parallelogram} after rotation or skew changes that category. A Square similarly widens
+    # to Rect after unequal scaling.
+    # @example Inspect corners, sides, and containment
+    #   rect = Sevgi::Geometry::Rect[8, 4, position: [2, 3]]
+    #   rect.top_left.deconstruct # => [2.0, 3.0]
+    #   rect.right.length         # => 4.0
+    #   rect.inside?([5, 5])      # => true
+    # @example Observe semantic widening after affine transforms
+    #   Sevgi::Geometry::Rect[8, 4].rotate(30).class # => Sevgi::Geometry::Parallelogram
+    #   Sevgi::Geometry::Square[4].scale(2, 1).class # => Sevgi::Geometry::Rect
+    # @!attribute [r] A
+    #   @return [Sevgi::Geometry::Point] top-left vertex
+    # @!attribute [r] B
+    #   @return [Sevgi::Geometry::Point] top-right vertex
+    # @!attribute [r] C
+    #   @return [Sevgi::Geometry::Point] bottom-right vertex
+    # @!attribute [r] D
+    #   @return [Sevgi::Geometry::Point] bottom-left vertex
+    # @!attribute [r] AB
+    #   @return [Sevgi::Geometry::Line] top side
+    # @!attribute [r] BC
+    #   @return [Sevgi::Geometry::Line] right side
+    # @!attribute [r] CD
+    #   @return [Sevgi::Geometry::Line] bottom side
+    # @!attribute [r] DA
+    #   @return [Sevgi::Geometry::Line] left side
+    # @!method perimeter
+    #   Returns the closed path perimeter.
+    #   @return [Float]
     class Rect < RectBase
       # @overload [](width, height, position: Origin)
       #   Builds a rectangle from size and top-left position.
@@ -15,8 +44,30 @@ module Sevgi
       #   @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(...)
+      #   @raise [Sevgi::Geometry::Error] when position cannot be coerced or a dimension is negative
+      # @example Mathematical notation and English convenience are equivalent
+      #   Sevgi::Geometry::Rect[3, 4] == Sevgi::Geometry::Rect.from_size(3, 4)
+      def self.[](width, height, position: Origin) = construct(width, height, position:)
+
+      # Constructs a rectangle for canonical size notation.
+      # @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 or a dimension is invalid
+      # @api private
+      def self.construct(width, height, position:)
+        width = dimension!(:width, width)
+        height = dimension!(:height, height)
+
+        new_by_segments(
+          Segment.rightward(width),
+          Segment.downward(height),
+          Segment.leftward(width),
+          Segment.upward(height),
+          position:
+        )
+      end
 
       # @overload call(top_left, bottom_right)
       #   Builds a rectangle from two opposite corners.
@@ -24,46 +75,96 @@ module Sevgi
       #   @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(...)
+      # @example Mathematical notation and English convenience are equivalent
+      #   Sevgi::Geometry::Rect.([0, 0], [3, 4]) == Sevgi::Geometry::Rect.from_corners([0, 0], [3, 4])
+      def self.call(top_left, bottom_right)
+        top_left, bottom_right = Tuples[Point, top_left, bottom_right]
+        left, right = [top_left.x, bottom_right.x].minmax
+        top, bottom = [top_left.y, bottom_right.y].minmax
+        width, height = right - left, bottom - top
+
+        if self <= Square
+          Error.("Square corners must define equal dimensions") unless F.eq?(width, height)
+
+          return self[width, position: [left, top]]
+        end
+
+        self[width, height, position: [left, top]]
+      end
 
       # 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
-
-        new_by_points(
-          top_left,
-          top_left.translate(width, 0.0),
-          bottom_right,
-          bottom_right.translate(-width, 0.0)
-        )
-      end
+      def self.from_corners(top_left, bottom_right) = call(top_left, bottom_right)
 
       # 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.rightward(width),
-          Segment.downward(height),
-          Segment.leftward(width),
-          Segment.upward(height),
-          position:
-        )
+      # @raise [Sevgi::Geometry::Error] when position cannot be coerced or a dimension is negative
+      def self.from_size(width, height, position: Origin) = self[width, height, position:]
+
+      class << self
+        private
+
+        def affine(*points)
+          left, right, top, bottom = bounds(points)
+          width, height = right - left, bottom - top
+
+          unless axis_aligned?(points, left, right, top, bottom)
+            return Parallelogram.call(*points.first(4))
+          end
+
+          klass = self <= Square && F.eq?(width, height) ? Square : Rect
+          return klass[width, position: [left, top]] if klass == Square
+
+          klass[width, height, position: [left, top]]
+        end
+
+        def approximate(*points)
+          new_by_points!(*points)
+        rescue Error
+          return Rect.send(:new_by_points!, *points) if self <= Square
+
+          super
+        end
+
+        def axis_aligned?(points, left, right, top, bottom)
+          expected = [[left, top], [right, top], [right, bottom], [left, bottom]]
+          vertices = points.first(4)
+
+          expected.all? { |corner| vertices.any? { it.eq?(Point[*corner]) } }
+        end
+
+        def bounds(points)
+          vertices = points.first(4)
+          [vertices.map(&:x).min, vertices.map(&:x).max, vertices.map(&:y).min, vertices.map(&:y).max]
+        end
+
+        def dimension!(name, value)
+          value = Real[name, value]
+          Error.("Rectangle #{name} cannot be negative") if value.negative?
+
+          value
+        end
       end
 
+      private_class_method :construct, :from_points, :from_segments
+
       # 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, **)
 
+      private :draw!
+
+      # Returns the rectangle center.
+      # @return [Sevgi::Geometry::Point]
+      def center = Point.midpoint(top_left, bottom_right)
+
       # Returns rectangle height.
       # @return [Float]
       def height = @height ||= segments[1].length
@@ -111,19 +212,52 @@ module Sevgi
       %i[top right bottom left].each_with_index do |side, i|
         define_method(side) { lines[i] }
       end
+
+      private
+
+      def validate_geometry!
+        left, right, top, bottom = self.class.send(:bounds, points)
+        expected = [[left, top], [right, top], [right, bottom], [left, bottom], [left, top]]
+        valid = points.zip(expected).all? { |point, pair| point.eq?(Point[*pair]) }
+
+        Error.("Rectangle points must form an axis-aligned rectangle") unless valid
+      end
     end
 
-    # Rectangle with equal width and height.
+    # Rectangle with equal width and height. Use {#width} or {#height} for its side length. Inherited
+    # {Element::Lined#length} returns the complete path length.
+    # @example Construct the same square from opposite corners
+    #   Sevgi::Geometry::Square.([0, 0], [5, 5]) == Sevgi::Geometry::Square.from_corners([0, 0], [5, 5])
     class Square < Rect
-      # @return [Float] side length
-      alias length width
+      # 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 or length is negative
+      # @example Mathematical notation and English convenience are equivalent
+      #   Sevgi::Geometry::Square[5] == Sevgi::Geometry::Square.from_size(5)
+      def self.[](length, position: Origin) = construct(length, length, position:)
+
+      # Builds a square 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::Square]
+      # @raise [Sevgi::Geometry::Error] when points are invalid or define unequal dimensions
+      def self.from_corners(top_left, bottom_right) = call(top_left, bottom_right)
 
       # 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:)
+      # @raise [Sevgi::Geometry::Error] when position or length is invalid
+      def self.from_size(length, position: Origin) = self[length, position:]
+
+      private
+
+      def validate_geometry!
+        super
+        Error.("Square sides must have equal length") unless F.eq?(width, height)
+      end
     end
   end
 end

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

@@ -7,12 +7,53 @@ module Sevgi
     TriangleBase = Element.lined(3)
     private_constant :TriangleBase
 
-    # Closed three-sided element built from two non-collinear adjacent segments.
+    # Closed three-sided element built from non-collinear segments or points. Every construction path rejects
+    # degenerate triangles. Affine operations retain Triangle when the transformed points remain non-degenerate.
+    # @!method self.call(*points)
+    #   Builds a triangle from three boundary points.
+    #   @param points [Array<Sevgi::Geometry::Point, Array<Numeric>>] three boundary points
+    #   @return [Sevgi::Geometry::Triangle]
+    #   @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or form a degenerate triangle
+    # @!method self.from_segments(segment_a, segment_b, position: Origin)
+    #   Builds a triangle from two adjacent segments and derives the closing side.
+    #   @param segment_a [Sevgi::Geometry::Segment, Array<Numeric>] first adjacent segment
+    #   @param segment_b [Sevgi::Geometry::Segment, Array<Numeric>] second adjacent segment
+    #   @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
+    #   @return [Sevgi::Geometry::Triangle]
+    #   @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or form a degenerate triangle
+    # @!method self.from_points(*points)
+    #   Builds a triangle from three boundary points.
+    #   @param points [Array<Sevgi::Geometry::Point, Array<Numeric>>] three boundary points
+    #   @return [Sevgi::Geometry::Triangle]
+    #   @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or form a degenerate triangle
+    # @!attribute [r] A
+    #   @return [Sevgi::Geometry::Point] first vertex
+    # @!attribute [r] B
+    #   @return [Sevgi::Geometry::Point] second vertex
+    # @!attribute [r] C
+    #   @return [Sevgi::Geometry::Point] third vertex
+    # @!attribute [r] AB
+    #   @return [Sevgi::Geometry::Line] side from A to B
+    # @!attribute [r] BC
+    #   @return [Sevgi::Geometry::Line] side from B to C
+    # @!attribute [r] CA
+    #   @return [Sevgi::Geometry::Line] side from C to A
+    # @!method perimeter
+    #   Returns the closed path perimeter.
+    #   @return [Float]
+    # @example Pair mathematical notation with English conveniences
+    #   Sevgi::Geometry::Triangle[[2, 0], [2, 90]] == Sevgi::Geometry::Triangle.from_segments([2, 0], [2, 90])
+    #   Sevgi::Geometry::Triangle.([0, 0], [2, 0], [2, 2]) == Sevgi::Geometry::Triangle.from_points([0, 0], [2, 0], [2, 2])
+    # @example Use named vertices and sides
+    #   triangle = Sevgi::Geometry::Triangle.([0, 0], [3, 0], [3, 4])
+    #   triangle.C.deconstruct # => [3.0, 4.0]
+    #   triangle.AB.length     # => 3.0
+    #   triangle.perimeter     # => 12.0
     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
+      # 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
@@ -27,21 +68,26 @@ module Sevgi
         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
+      class << self
+        private
+
+        def 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 validate!(a, b)
+          middle = a.ending(Origin)
+          return unless F.zero?(a.length) || F.zero?(b.length) || Point.collinear?(Origin, middle, b.ending(middle))
 
-      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!
+      private
+
+      def validate_geometry!
+        self.class.send(:validate!, segments[0], segments[1])
+      end
     end
   end
 end