sevgi-geometry 0.95.0 → 0.98.2

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

@@ -7,7 +7,32 @@ module Sevgi
     LineBase = Element.lined(1, open: true)
     private_constant :LineBase
 
-    # Open lined element with one segment.
+    # Finite, directed line between two endpoints.
+    #
+    # Direction affects {#left?}, {#right?}, and the sign of {#shift}. Use
+    # {#equation} when the corresponding infinite line is required; {#over?}
+    # deliberately tests only the finite extent between the endpoints.
+    # @example Query sides of a directed line in screen coordinates
+    #   line = Sevgi::Geometry::Line.([0, 0], [10, 0])
+    #   line.left?([5, -2])  # => true
+    #   line.right?([5, 2])  # => true
+    #   line.shift(2).starting.deconstruct # => [0.0, -2.0]
+    # @example Distinguish the finite segment from its infinite equation
+    #   line = Sevgi::Geometry::Line.([0, 0], [10, 0])
+    #   line.over?([5, 0])  # => true
+    #   line.over?([15, 0]) # => false
+    # @!method self.call(starting, ending)
+    #   Builds a line from two endpoints.
+    #   @param starting [Sevgi::Geometry::Point, Array<Numeric>] starting point
+    #   @param ending [Sevgi::Geometry::Point, Array<Numeric>] ending point
+    #   @return [Sevgi::Geometry::Line]
+    #   @raise [Sevgi::Geometry::Error] when either point cannot be coerced
+    # @!attribute [r] A
+    #   @return [Sevgi::Geometry::Point] starting point
+    # @!attribute [r] B
+    #   @return [Sevgi::Geometry::Point] ending point
+    # @!attribute [r] AB
+    #   @return [Sevgi::Geometry::Line] line from A to B
     class Line < LineBase
       # @overload [](length, angle, position: Origin)
       #   Builds a line from length and angle.
@@ -15,16 +40,18 @@ module Sevgi
       #   @param angle [Numeric] clockwise angle in degrees
       #   @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
       #   @return [Sevgi::Geometry::Line]
-      #   @raise [Sevgi::Geometry::Error] when position cannot be coerced
-      def self.[](...) = from_length_angle(...)
+      #   @raise [Sevgi::Geometry::Error] when length, angle, or position cannot be coerced to finite geometry values
+      # @example Mathematical notation and English convenience are equivalent
+      #   Sevgi::Geometry::Line[5, 30] == Sevgi::Geometry::Line.from_length_angle(5, 30)
+      def self.[](length, angle, position: Origin) = new_by_segments(Segment[length, angle], position:)
 
       # Builds a line from length and angle.
       # @param length [Numeric] line length
       # @param angle [Numeric] clockwise angle in degrees
       # @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
       # @return [Sevgi::Geometry::Line]
-      # @raise [Sevgi::Geometry::Error] when position cannot be coerced
-      def self.from_length_angle(length, angle, position: Origin) = new_by_segments(Segment[length, angle], position:)
+      # @raise [Sevgi::Geometry::Error] when length, angle, or position cannot be coerced to finite geometry values
+      def self.from_length_angle(length, angle, position: Origin) = self[length, angle, position:]
 
       # @overload from_points(starting, ending)
       #   Builds a line from two endpoints.
@@ -32,7 +59,11 @@ module Sevgi
       #   @param ending [Sevgi::Geometry::Point, Array<Numeric>] ending point
       #   @return [Sevgi::Geometry::Line]
       #   @raise [Sevgi::Geometry::Error] when either point cannot be coerced
-      def self.from_points(...) = new_by_points(...)
+      # @example Mathematical notation and English convenience are equivalent
+      #   Sevgi::Geometry::Line.([0, 0], [3, 4]) == Sevgi::Geometry::Line.from_points([0, 0], [3, 4])
+      def self.from_points(...) = call(...)
+
+      private_class_method :from_segments
 
       # Returns the clockwise line angle in degrees.
       # @return [Float]
@@ -42,21 +73,19 @@ module Sevgi
       # @return [Sevgi::Geometry::Point]
       def ending = points.last
 
-      # Reports whether a point is left of the line equation.
+      # Reports whether a point is left of the directed line from {#starting} to {#ending} in screen coordinates.
+      # Points on the infinite line are on neither side. A zero-length line has no direction and returns false.
       # @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)
-
-      # Returns the line segment length.
-      # @return [Float]
-      def length = head.length
+      def left?(point) = F.lt?(side(point), 0.0)
 
-      # Reports whether a point is right of the line equation.
+      # Reports whether a point is right of the directed line from {#starting} to {#ending} in screen coordinates.
+      # Points on the infinite line are on neither side. A zero-length line has no direction and returns false.
       # @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 right?(point) = F.gt?(side(point), 0.0)
 
       # Returns the starting point.
       # @return [Sevgi::Geometry::Point]
@@ -67,6 +96,8 @@ module Sevgi
       # @return [Object] graphics node command result
       def draw!(node, **) = node.LineTo(x1: position.x, y1: position.y, x2: ending.x, y2: ending.y, **)
 
+      private :draw!
+
       # Reports whether a point lies on the finite line segment.
       # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
       # @return [Boolean]
@@ -78,12 +109,26 @@ module Sevgi
       end
 
       # Returns a parallel line shifted by a signed perpendicular offset.
+      # Positive distance moves to the directed line's left in screen coordinates; reversing the endpoints reverses the
+      # shift direction.
       # @param distance [Numeric] signed perpendicular offset
       # @return [Sevgi::Geometry::Line]
-      def shift(distance) = translate(distance * F.sin(angle), -distance * F.cos(angle))
+      # @raise [Sevgi::Geometry::Error] when distance is not a finite real number
+      def shift(distance)
+        distance = Real[:distance, distance]
+        translate(distance * F.sin(angle), -distance * F.cos(angle))
+      end
 
       private
 
+      def cross(ax, ay, bx, by) = (ax * by) - (ay * bx)
+      def delta(from, to) = [to.x - from.x, to.y - from.y]
+
+      def side(point)
+        point = Tuple[Point, point]
+        cross(*delta(starting, ending), *delta(starting, point))
+      end
+
       def within_range?(point)
         point = point.approx
         points = [starting.approx, ending.approx]

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

@@ -7,53 +7,134 @@ module Sevgi
     ParallelogramBase = Element.lined(4)
     private_constant :ParallelogramBase
 
-    # Closed four-sided element built from horizontal and vertical segments.
+    # Closed four-sided element whose opposite sides are equal and parallel. Every construction path rejects
+    # degenerate or unrelated side pairs; affine operations preserve the class while that invariant holds.
+    # @!method self.call(*points)
+    #   Builds a parallelogram from four boundary points.
+    #   @param points [Array<Sevgi::Geometry::Point, Array<Numeric>>] four boundary points
+    #   @return [Sevgi::Geometry::Parallelogram]
+    #   @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or do not form a parallelogram
+    # @!method self.from_segments(base, side, position: Origin)
+    #   Builds a parallelogram from two adjacent segments and derives their opposites.
+    #   @param base [Sevgi::Geometry::Segment, Array<Numeric>] segment from A to B
+    #   @param side [Sevgi::Geometry::Segment, Array<Numeric>] segment from A to D
+    #   @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
+    #   @return [Sevgi::Geometry::Parallelogram]
+    #   @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or do not form a parallelogram
+    # @!method self.from_points(*points)
+    #   Builds a parallelogram from four boundary points.
+    #   @param points [Array<Sevgi::Geometry::Point, Array<Numeric>>] four boundary points
+    #   @return [Sevgi::Geometry::Parallelogram]
+    #   @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or do not form a parallelogram
+    # @!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] D
+    #   @return [Sevgi::Geometry::Point] fourth 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] CD
+    #   @return [Sevgi::Geometry::Line] side from C to D
+    # @!attribute [r] DA
+    #   @return [Sevgi::Geometry::Line] side from D to A
+    # @!method perimeter
+    #   Returns the closed path perimeter.
+    #   @return [Float]
+    # @example Pair mathematical notation with English conveniences
+    #   Sevgi::Geometry::Parallelogram[[2, 0], [2, -90]] ==
+    #     Sevgi::Geometry::Parallelogram.from_segments([2, 0], [2, -90])
+    #   points = [[0, 0], [2, 0], [2, 2], [0, 2]]
+    #   Sevgi::Geometry::Parallelogram.(*points) == Sevgi::Geometry::Parallelogram.from_points(*points)
+    # @example Compare vertices with the axis-aligned bounding box
+    #   shape = Sevgi::Geometry::Parallelogram.([1, 1], [5, 1], [7, 4], [3, 4])
+    #   shape.C.deconstruct # => [7.0, 4.0]
+    #   shape.box.width     # => 6.0
+    #   shape.box.height    # => 3.0
     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
+      # Builds a parallelogram from adjacent base and side segments. Both segments originate at `position`; `base`
+      # defines AB and `side` defines AD, regardless of their angles.
+      # @param base [Sevgi::Geometry::Segment, Array<Numeric>] segment from A to B
+      # @param side [Sevgi::Geometry::Segment, Array<Numeric>] segment from A to D
       # @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]
+      def self.[](base, side, position: Origin)
+        base, side = Tuples[Segment, base, side]
 
-        new_by_segments(horizontal, vertical.reverse, horizontal.reverse, vertical, position:)
+        new_by_segments(base, side.reverse, base.reverse, side, 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
+      # Builds a parallelogram from a base and bounding-height constraint. The constraint length is the target height;
+      # its signed angle is retained as the direction of the derived side while the component magnitude determines that
+      # side's non-negative length.
+      # @param base [Sevgi::Geometry::Segment, Array<Numeric>] segment from A to B
+      # @param constraint [Sevgi::Geometry::LengthAngle, Array<Numeric>] target height and side direction
       # @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]
+      # @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or the height constraint is infeasible
+      # @example Use an array constraint
+      #   Sevgi::Geometry::Parallelogram.new_by_height(base: [4, 0], constraint: [3, -90])
+      # @example Use a LengthAngle constraint
+      #   constraint = Sevgi::Geometry::LengthAngle.new(length: 3, angle: 90)
+      #   base = Sevgi::Geometry::Segment[4, 0]
+      #   Sevgi::Geometry::Parallelogram.new_by_height(base:, constraint:)
+      def self.new_by_height(base:, constraint:, position: Origin)
+        base = Tuple[Segment, base]
+        constraint = Tuple[LengthAngle, constraint]
 
-        height = tallness.length - horizontal.y.abs
-        angle = tallness.angle
-        length = height / F.sin(angle)
+        height = constraint.length - base.y.abs
+        angle = constraint.angle
+        sine = F.sin(angle)
+        Error.("Parallelogram height is smaller than its base span") if height.negative?
+        Error.("Parallelogram height constraint must have a vertical component") if F.zero?(sine)
 
-        self[horizontal, Segment[length, angle], position:]
+        self[base, Segment[height / sine.abs, 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
+      # Builds a parallelogram from a side and bounding-width constraint. The constraint length is the target width; its
+      # signed angle is retained as the direction of the derived base while the component magnitude determines that
+      # base's non-negative length.
+      # @param side [Sevgi::Geometry::Segment, Array<Numeric>] segment from A to D
+      # @param constraint [Sevgi::Geometry::LengthAngle, Array<Numeric>] target width and base direction
       # @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]
+      # @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or the width constraint is infeasible
+      # @example Use an array constraint
+      #   Sevgi::Geometry::Parallelogram.new_by_width(side: [3, 90], constraint: [4, 180])
+      # @example Use a LengthAngle constraint
+      #   constraint = Sevgi::Geometry::LengthAngle.new(length: 4, angle: 0)
+      #   side = Sevgi::Geometry::Segment[3, 90]
+      #   Sevgi::Geometry::Parallelogram.new_by_width(side:, constraint:)
+      def self.new_by_width(side:, constraint:, position: Origin)
+        side = Tuple[Segment, side]
+        constraint = Tuple[LengthAngle, constraint]
 
-        width = wideness.length - vertical.x.abs
-        angle = wideness.angle
-        length = width / F.cos(angle)
+        width = constraint.length - side.x.abs
+        angle = constraint.angle
+        cosine = F.cos(angle)
+        Error.("Parallelogram width is smaller than its side span") if width.negative?
+        Error.("Parallelogram width constraint must have a horizontal component") if F.zero?(cosine)
 
-        self[Segment[length, angle], vertical, position:]
+        self[Segment[width / cosine.abs, angle], side, position:]
       end
+
+      private
+
+      def validate_geometry!
+        a, b, c, d = segments
+        valid = opposite?(a, c) && opposite?(b, d) && !F.zero?(cross(a, b))
+
+        Error.("Parallelogram sides must be non-degenerate opposite pairs") unless valid
+      end
+
+      def cross(a, b) = (a.x * b.y) - (a.y * b.x)
+
+      def opposite?(a, b) = F.zero?(a.x + b.x) && F.zero?(a.y + b.y)
     end
   end
 end

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

@@ -7,8 +7,48 @@ module Sevgi
     PolygonBase = Element.lined
     private_constant :PolygonBase
 
-    # Variable-size closed lined element.
+    # Variable-size closed lined element with at least three vertices.
+    # @!method self.[](*segments, position: Origin)
+    #   Builds a polygon from boundary segments.
+    #   @param segments [Array<Sevgi::Geometry::Segment, Array<Numeric>>] boundary segments
+    #   @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
+    #   @return [Sevgi::Geometry::Polygon]
+    #   @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or do not form a polygon
+    # @!method self.call(*points)
+    #   Builds a polygon from boundary points.
+    #   @param points [Array<Sevgi::Geometry::Point, Array<Numeric>>] boundary points without a repeated closing point
+    #   @return [Sevgi::Geometry::Polygon]
+    #   @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or do not form a polygon
+    # @!method self.from_segments(*segments, position: Origin)
+    #   Builds a polygon from boundary segments.
+    #   @param segments [Array<Sevgi::Geometry::Segment, Array<Numeric>>] boundary segments
+    #   @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
+    #   @return [Sevgi::Geometry::Polygon]
+    #   @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or do not form a polygon
+    # @!method self.from_points(*points)
+    #   Builds a polygon from boundary points.
+    #   @param points [Array<Sevgi::Geometry::Point, Array<Numeric>>] boundary points without a repeated closing point
+    #   @return [Sevgi::Geometry::Polygon]
+    #   @raise [Sevgi::Geometry::Error] when inputs cannot be coerced or do not form a polygon
+    # @!method perimeter
+    #   Returns the closed path perimeter.
+    #   @return [Float]
+    # @example Pair point notation with its English convenience
+    #   points = [[0, 0], [2, 0], [1, 1]]
+    #   segments = Sevgi::Geometry::Polygon.(*points).segments
+    #   Sevgi::Geometry::Polygon[*segments] == Sevgi::Geometry::Polygon.from_segments(*segments)
+    #   Sevgi::Geometry::Polygon.(*points) == Sevgi::Geometry::Polygon.from_points(*points)
+    # @example Classify points against a closed boundary
+    #   polygon = Sevgi::Geometry::Polygon.([0, 0], [6, 0], [3, 4])
+    #   polygon.inside?([3, 2]) # => true
+    #   polygon.on?([3, 0])     # => true
+    #   polygon.outside?([7, 2]) # => true
     class Polygon < PolygonBase
+      private
+
+      def validate_geometry!
+        Error.("Polygon requires at least three vertices") if points.size < 4
+      end
     end
   end
 end

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

@@ -7,8 +7,43 @@ 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
+    # @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,92 @@ 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 rectangle height.
       # @return [Float]
       def height = @height ||= segments[1].length
@@ -111,19 +208,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