sevgi-geometry 0.73.2 → 0.93.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9be3893bcfca34cd9d7a2014de7fbb21ba0720e34625c700dcd9dd20b16f1c52
-  data.tar.gz: d9936cd27f1a5360163ef50ca926263b7d913bf3512b14006a504dd5c393d3aa
+  metadata.gz: 692e31b99ab3fb9e757badcf6b764bc5c788ed79a6d6955109e6edc44e9929b1
+  data.tar.gz: 92eb5d40058eeafafc625767e4abef2c201ee516fab38372bb1da440ec6c2c42
 SHA512:
-  metadata.gz: 452bdaf29a65ce32032326de0968852cb1449e4faefb5fe3ee24fe6cb8e7ea335d5760264fa08505c6a83f6f763585d9fd4c859b278c6d008ba00be58c7e4b18
-  data.tar.gz: 50f163f2a6d50e2bea7be781a45bba8a1dbdaaaf45a00004b73d8c58ac2306da54cf82a6418696fa11fa49ac47f562857f4b56a81007f0a73244cb9b67079713
+  metadata.gz: 6c741e60a6f2f37d0b6418cd2c574c9e6bae2bbc02ab0ee4835564bd49b9ddb68ceef420aacb62dfba25d405c0ad7c0db93efa1fa4c263839bb1dcb802010598
+  data.tar.gz: e596f27e84b36bcccabdb059c47641fdd468857595b60eda23592e4b69eccb59500159be5ece5b7f9a96e463bf4731a68ab13e7f1fedbe90094d71094fbe4b5a

data/README.md

@@ -0,0 +1,5 @@
+# Sevgi Geometry
+
+Provides small geometry primitives and operations for Sevgi drawings.
+
+See the root [README](../README.md) and the documentation site for usage.

data/lib/sevgi/geometry/element.rb

@@ -2,47 +2,105 @@
 
 module Sevgi
   module Geometry
+    # Base class for geometric elements.
     class Element
+      # @overload lined(size = Undefined, open: false)
+      #   Builds a lined element subclass.
+      #   @param size [Integer, Sevgi::Undefined] segment count for fixed-size elements, or Undefined for variable size
+      #   @param open [Boolean] true for an open path, false for a closed path
+      #   @return [Class] subclass of {Sevgi::Geometry::Element::Lined}
       def self.lined(...) = Lined.build(...)
 
+      # @overload arced(*args)
+      #   Builds an arced element subclass.
+      #   @api private
+      #   @param args [Array<Object>] arced factory arguments
+      #   @return [Class]
+      #   @raise [NoMethodError] until arced elements are implemented
       def self.arced(...) = Arced.build(...)
 
       # Core API
 
+      # Returns a copy moved to a point and optional offset.
+      # @param point [Sevgi::Geometry::Point, Array<Numeric>, nil] target position, or nil to keep current position
+      # @param dx [Numeric] additional x offset
+      # @param dy [Numeric] additional y offset
+      # @return [Sevgi::Geometry::Element] translated element
+      # @raise [Sevgi::Geometry::Error] when point cannot be coerced
       def at(point = nil, dx: 0, dy: 0)
+        point = point ? Tuple[Point, point] : position
+
         translate(
-          ((point ||= position).x - position.x) + dx,
+          (point.x - position.x) + dx,
           (point.y - position.y) + dy
         )
       end
 
-      def box = raise NoMethodError, "#{self.class}#box must be implemented"
-
-      def equations = raise NoMethodError, "#{self.class}#equations must be implemented"
-
+      # Returns the bounding rectangle.
+      # @abstract Subclasses implement element-specific bounds.
+      # @return [Sevgi::Geometry::Rect]
+      # @raise [Sevgi::PanicError] when a subclass does not implement box
+      def box = PanicError.("#{self.class}#box must be implemented")
+
+      # Returns equations that define the element boundary.
+      # @abstract Subclasses implement element-specific equations.
+      # @return [Array<Sevgi::Geometry::Equation>]
+      # @raise [Sevgi::PanicError] when a subclass does not implement equations
+      def equations = PanicError.("#{self.class}#equations must be implemented")
+
+      # Reports whether the element has zero bounding width and height.
+      # @param precision [Integer, nil] decimal precision, or nil for the current function default
+      # @return [Boolean]
       def ignorable?(precision: nil) = F.zero?(box.width, precision:) && F.zero?(box.height, precision:)
 
-      def position = raise NoMethodError, "#{self.class}#position must be implemented"
+      # Returns the element position.
+      # @abstract Subclasses implement element-specific positioning.
+      # @return [Sevgi::Geometry::Point]
+      # @raise [Sevgi::PanicError] when a subclass does not implement position
+      def position = PanicError.("#{self.class}#position must be implemented")
 
-      def translate(_x, _y) = raise NoMethodError, "#{self.class}#translate must be implemented"
+      # Returns a translated copy.
+      # @abstract Subclasses implement element-specific translation.
+      # @param _x [Numeric] x offset
+      # @param _y [Numeric] y offset
+      # @return [Sevgi::Geometry::Element]
+      # @raise [Sevgi::PanicError] when a subclass does not implement translate
+      def translate(_x, _y) = PanicError.("#{self.class}#translate must be implemented")
 
       # rubocop:disable Metrics/ClassLength
+      # Element whose boundary is represented by straight segments.
       class Lined < self
+        # Open lined element base class.
         Open = Class.new(self) do
+          # Draws the element as an SVG polyline.
+          # @param node [Object] graphics node receiving the drawing command
+          # @return [Object] graphics node command result
           def draw!(node, **) = node.polyline(points: points.map { it.deconstruct.join(",") }, **)
         end
 
+        # Closed lined element base class.
         Close = Class.new(self) do
+          # Creates a closed element from points, appending the first point.
+          # @param points [Array<Sevgi::Geometry::Point, Array<Numeric>>] boundary points
+          # @return [Sevgi::Geometry::Element::Lined]
+          # @raise [Sevgi::Geometry::Error] when any point cannot be coerced
           def self.new_by_points(*points) = super(*points, points.first)
 
+          # Draws the element as an SVG polygon.
+          # @param node [Object] graphics node receiving the drawing command
+          # @return [Object] graphics node command result
           def draw!(node, **) = node.polygon(points: points.map { it.deconstruct.join(",") }, **)
         end
 
         # Class methods
 
+        # Point shortcut names generated for fixed-size lined elements.
         SHORTCUTS = ("A".."Z").to_a.freeze
 
-        # rubocop:disable Metrics/MethodLength
+        # Builds a concrete lined element class.
+        # @param size [Integer, Sevgi::Undefined] segment count for fixed-size elements, or Undefined for variable size
+        # @param open [Boolean] true for an open path, false for a closed path
+        # @return [Class] lined element subclass
         def self.build(size = Undefined, open: false)
           Class.new(open ? Open : Close) do
             define_singleton_method(:close?) { !open }
@@ -53,33 +111,64 @@ module Sevgi
 
             define_singleton_method(:size) { size }
 
-            unless size == Undefined
-              SHORTCUTS[..size.clamp(..SHORTCUTS.size)].each_with_index do |name, i|
-                define_method(name) { points[i] or Error.("No such point: #{name}") }
-              end
-
-              methods = SHORTCUTS[..size.clamp(..SHORTCUTS.size)].each_cons(2).with_index.map do |names, i|
-                define_method(name = names.join) { lines[i] or Error.("No such line: #{name}") }
-              end
-
-              alias_method("#{SHORTCUTS[size - 1]}#{SHORTCUTS.first}", methods.last)
-            end
+            Lined.send(:define_shortcuts, self, size, open:) unless size == Undefined
           end
-          # rubocop:enable Metrics/MethodLength
         end
 
-        def self.[](...) = new_by_segments(...)
-
-        def self.call(...) = new_by_points(...)
-
+        # @overload [](*segments, position: Origin)
+        #   Builds an element from segments.
+        #   @param segments [Array<Sevgi::Geometry::Segment, Array<Numeric>>] boundary segments
+        #   @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
+        #   @return [Sevgi::Geometry::Element::Lined]
+        #   @raise [Sevgi::Geometry::Error] when segments or position cannot be coerced
+        def self.[](...) = from_segments(...)
+
+        # @overload call(*points)
+        #   Builds an element from points.
+        #   @param points [Array<Sevgi::Geometry::Point, Array<Numeric>>] boundary points
+        #   @return [Sevgi::Geometry::Element::Lined]
+        #   @raise [Sevgi::Geometry::Error] when points cannot be coerced
+        def self.call(...) = from_points(...)
+
+        # @overload from_points(*points)
+        #   Builds an element from points.
+        #   @param points [Array<Sevgi::Geometry::Point, Array<Numeric>>] boundary points
+        #   @return [Sevgi::Geometry::Element::Lined]
+        #   @raise [Sevgi::Geometry::Error] when points cannot be coerced
+        def self.from_points(...) = new_by_points(...)
+
+        # @overload from_segments(*segments, position: Origin)
+        #   Builds an element from segments.
+        #   @param segments [Array<Sevgi::Geometry::Segment, Array<Numeric>>] boundary segments
+        #   @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
+        #   @return [Sevgi::Geometry::Element::Lined]
+        #   @raise [Sevgi::Geometry::Error] when segments or position cannot be coerced
+        def self.from_segments(...) = new_by_segments(...)
+
+        # @overload new_by_points(*points)
+        #   Builds an element from points, applying closed-path behavior where appropriate.
+        #   @param points [Array<Sevgi::Geometry::Point, Array<Numeric>>] boundary points
+        #   @return [Sevgi::Geometry::Element::Lined]
+        #   @raise [Sevgi::Geometry::Error] when points cannot be coerced
         def self.new_by_points(...) = new_by_points!(...)
 
+        # Builds an element from an exact point path.
+        #
+        # Closed classes require the closing point to be supplied by the caller.
+        # @param points [Array<Sevgi::Geometry::Point, Array<Numeric>>] exact boundary points
+        # @return [Sevgi::Geometry::Element::Lined]
+        # @raise [Sevgi::Geometry::Error] when points cannot be coerced or do not satisfy the class path contract
         def self.new_by_points!(*points)
           new do
             @points = Tuples[Point, *points]
           end
         end
 
+        # Builds an element from segments and a start position.
+        # @param segments [Array<Sevgi::Geometry::Segment, Array<Numeric>>] boundary segments
+        # @param position [Sevgi::Geometry::Point, Array<Numeric>] starting point
+        # @return [Sevgi::Geometry::Element::Lined]
+        # @raise [Sevgi::Geometry::Error] when segments or position cannot be coerced
         def self.new_by_segments(*segments, position: Origin)
           new do
             @position = Tuple[Point, position]
@@ -89,6 +178,29 @@ module Sevgi
 
         private_class_method(:new)
 
+        def self.define_line_shortcuts(klass, point_names, open:)
+          line_names = point_names.each_cons(2).map(&:join)
+          line_names << "#{point_names.last}#{point_names.first}" if !open && point_names.any?
+
+          line_names.each_with_index do |name, i|
+            klass.define_method(name) { lines[i] or Error.("No such line: #{name}") }
+          end
+        end
+
+        def self.define_point_shortcuts(klass, point_names)
+          point_names.each_with_index do |name, i|
+            klass.define_method(name) { points[i] or Error.("No such point: #{name}") }
+          end
+        end
+
+        def self.define_shortcuts(klass, size, open:)
+          point_names = SHORTCUTS.first([open ? size + 1 : size, SHORTCUTS.size].min)
+          define_point_shortcuts(klass, point_names)
+          define_line_shortcuts(klass, point_names, open:)
+        end
+
+        private_class_method :define_line_shortcuts, :define_point_shortcuts, :define_shortcuts
+
         def initialize(&block)
           super()
 
@@ -104,6 +216,8 @@ module Sevgi
 
         # Core methods
 
+        # Returns an element with approximate points and segments.
+        # @return [Sevgi::Geometry::Element::Lined]
         def approx
           points, segments = points(true), segments(true)
           self.class.send(:new) do
@@ -111,20 +225,33 @@ module Sevgi
           end
         end
 
+        # @overload draw(node, **attributes)
+        #   Draws an approximate element into a graphics node.
+        #   @param node [Object] graphics node receiving the drawing command
+        #   @param attributes [Hash] drawing attributes
+        #   @return [Object] graphics node command result
         def draw(...)
           approx.draw!(...)
         end
 
+        # Returns element points.
+        # @param approximate [Boolean] true to round points with the current function precision
+        # @return [Array<Sevgi::Geometry::Point>]
         def points(approximate = false)
-          approximate ? (@points_approx ||= @points.map(&:approx)) : @points
+          approximate ? @points.map(&:approx) : @points
         end
 
+        # Returns the first point.
+        # @return [Sevgi::Geometry::Point]
         def position
           @position ||= points.first
         end
 
+        # Returns element segments.
+        # @param approximate [Boolean] true to round segments with the current function precision
+        # @return [Array<Sevgi::Geometry::Segment>]
         def segments(approximate = false)
-          approximate ? (@segments_approx ||= @segments.map(&:approx)) : @segments
+          approximate ? @segments.map(&:approx) : @segments
         end
 
         # Affinity methods
@@ -137,16 +264,29 @@ module Sevgi
 
         # Equality methods
 
+        # Reports strict element equality by class and approximate points.
+        # @param other [Object] object to compare
+        # @return [Boolean]
         def eql?(other) = self.class == other.class && points(true) == other.points(true)
 
+        # Returns a hash compatible with strict equality.
+        # @return [Integer]
         def hash = [self.class, *points(true)].hash
 
         alias == eql?
 
         # Interaction methods
 
+        # Returns boundary equations for all lines.
+        # @return [Array<Sevgi::Geometry::Equation::Linear>]
         def equations = @equations ||= lines.map(&:equation)
 
+        # Intersects the element boundary with an equation.
+        # @param equation [Sevgi::Geometry::Equation] equation to intersect with
+        # @param precision [Integer, nil] decimal precision, or nil for the current function default
+        # @return [Array<Sevgi::Geometry::Point>] unique boundary intersection points
+        # @raise [Sevgi::Geometry::Error] when equation is not an equation
+        # @raise [Sevgi::PanicError] when the equation combination is not implemented
         def intersection(equation, precision: nil)
           equations
             .map do |candidate|
@@ -158,30 +298,68 @@ module Sevgi
 
         # Properties
 
+        # Returns a line by index.
+        # @param i [Integer] line index
+        # @return [Sevgi::Geometry::Line]
+        # @raise [Sevgi::Geometry::Error] when no line exists for index
         def [](i) = lines[i].tap { |line| Error.("No line exist for index: #{i}") unless line }
 
-        def box = Rect.([(xs = points.map(&:x)).min, (ys = points.map(&:y)).min], [xs.max, ys.max])
+        # Returns the bounding rectangle.
+        # @return [Sevgi::Geometry::Rect]
+        def box = Rect.from_corners([(xs = points.map(&:x)).min, (ys = points.map(&:y)).min], [xs.max, ys.max])
 
+        # Returns a point by index.
+        # @param i [Integer] point index
+        # @return [Sevgi::Geometry::Point]
+        # @raise [Sevgi::Geometry::Error] when no point exists for index
         def call(i) = points[i].tap { Error.("No point exist for index: #{i}") unless it }
 
+        # Returns the first segment.
+        # @return [Sevgi::Geometry::Segment]
         def head = @head ||= segments.first
 
+        # Returns boundary lines derived from segments and points.
+        # @return [Array<Sevgi::Geometry::Line>]
         def lines
           @lines ||= segments.zip(points[...segments.size]).map { |segment, position|
             segment.line(position)
           }
         end
 
+        # Returns the sum of segment lengths.
+        # @return [Float]
         def perimeter = @perimeter ||= segments.sum(&:length)
 
+        # Returns the last segment.
+        # @return [Sevgi::Geometry::Segment]
         def tail = @tail ||= segments.last
 
         # Relation methods
 
-        def inside?(point) = on?(point) || pnpoly(points, point)
+        # Reports whether a point is inside or on the boundary.
+        # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
+        # @return [Boolean]
+        # @raise [Sevgi::Geometry::Error] when point cannot be coerced
+        def inside?(point)
+          point = Tuple[Point, point]
+
+          on?(point) || pnpoly(points, point)
+        end
 
-        def on?(point) = lines.any? { it.over?(point) }
+        # Reports whether a point is on the boundary.
+        # @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]
+
+          lines.any? { it.over?(point) }
+        end
 
+        # Reports whether a point is outside the element boundary.
+        # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
+        # @return [Boolean]
+        # @raise [Sevgi::Geometry::Error] when point cannot be coerced
         def outside?(point) = !inside?(point)
 
         private
@@ -236,17 +414,19 @@ module Sevgi
         end
       end
 
+      # Reserved base for future arced elements.
+      # @api private
       class Arced < self
       end
       # rubocop:enable Metrics/ClassLength
     end
 
     require_relative "elements/line"
-    require_relative "elements/parm"
+    require_relative "elements/parallelogram"
     require_relative "elements/polygon"
     require_relative "elements/polyline"
     require_relative "elements/rect"
-    require_relative "elements/tri"
+    require_relative "elements/triangle"
 
     require_relative "elements/circle"
     require_relative "elements/curve"

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

@@ -4,8 +4,37 @@ require "forwardable"
 
 module Sevgi
   module Geometry
-    class Line < Element.lined(1, open: true)
-      def self.[](length, angle, position: Origin) = new_by_segments(Segment[length, angle], position:)
+    # Generated superclass for Line.
+    # @api private
+    LineBase = Element.lined(1, open: true)
+    private_constant :LineBase
+
+    # Open lined element with one segment.
+    class Line < LineBase
+      # @overload [](length, angle, position: Origin)
+      #   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(...)
+
+      # 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:)
+
+      # @overload from_points(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
+      def self.from_points(...) = new_by_points(...)
 
       extend Forwardable
 
@@ -16,15 +45,25 @@ module Sevgi
 
       def_delegators :equation, :left?, :right?
 
-      alias a angle
-      alias l length
+      # Draws the line into a graphics node.
+      # @param node [Object] graphics node receiving the drawing command
+      # @return [Object] graphics node command result
+      def draw!(node, **) = node.LineTo(x1: position.x, y1: position.y, x2: ending.x, y2: ending.y, **)
 
-      def draw!(node, **) = node.Cline(x1: position.x, y1: position.y, x2: ending.x, y2: ending.y, **)
+      # Reports whether a point lies on the finite line segment.
+      # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
+      # @return [Boolean]
+      # @raise [Sevgi::Geometry::Error] when point cannot be coerced
+      def over?(point)
+        point = Tuple[Point, point]
 
-      # TODO: xxx
-      def over?(point) = within_range?(point) && equation.on?(point)
+        within_range?(point) && equation.on?(point)
+      end
 
-      def shift(distance) = translate(distance * F.sin(angle), distance * F.cos(angle))
+      # Returns a parallel line shifted by a signed perpendicular offset.
+      # @param distance [Numeric] signed perpendicular offset
+      # @return [Sevgi::Geometry::Line]
+      def shift(distance) = translate(distance * F.sin(angle), -distance * F.cos(angle))
 
       private
 

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,20 +43,33 @@ 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
 
       %i[top_left top_right bottom_right bottom_left].each_with_index do |corner, i|
@@ -40,10 +81,17 @@ module Sevgi
       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