sevgi-geometry 0.95.0 → 1.0.0

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

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Geometry
+    # rubocop:disable Metrics/ClassLength
+
+    # Immutable ellipse with positive radii, a center, and clockwise axis rotation.
+    # Parameter angles belong to the local ellipse axes, not to polar directions from the center.
+    # @example Select a finite boundary and inspect its endpoints
+    #   ellipse = Sevgi::Geometry::Ellipse[4, 2, position: [10, 20]]
+    #   ellipse.point(90).deconstruct # => [10.0, 22.0]
+    #   ellipse.arc(starting_angle: 0, extent: 90).ending == ellipse.point(90)
+    class Ellipse < Element::Arced
+      # Builds an ellipse from local radii and its position.
+      # @param rx [Numeric] positive local x radius
+      # @param ry [Numeric] positive local y radius
+      # @param position [Sevgi::Geometry::Point, Array<Numeric>] ellipse center
+      # @param rotation [Numeric] clockwise rotation in degrees
+      # @return [Sevgi::Geometry::Ellipse]
+      # @raise [Sevgi::Geometry::Error] when inputs are not finite real values or a radius is not positive
+      def self.[](rx, ry, position: Origin, rotation: 0) = new(rx, ry, position:, rotation:)
+
+      def self.close? = true
+      private_class_method :close?
+
+      # @return [Sevgi::Geometry::Point] ellipse center
+      attr_reader :position
+      # @return [Float] clockwise rotation of the local axes in degrees
+      attr_reader :rotation
+      # @return [Float] positive local x radius
+      attr_reader :rx
+      # @return [Float] positive local y radius
+      attr_reader :ry
+
+      # Creates an ellipse. Use the bracket constructor.
+      # @param rx [Numeric] positive local x radius
+      # @param ry [Numeric] positive local y radius
+      # @param position [Sevgi::Geometry::Point, Array<Numeric>] center
+      # @param rotation [Numeric] clockwise rotation in degrees
+      # @return [void]
+      # @raise [Sevgi::Geometry::Error] when an input is invalid
+      def initialize(rx, ry, position:, rotation:)
+        super()
+        @rx, @ry = [[:rx, rx], [:ry, ry]].map do |field, value|
+          value = Real[field, value]
+          Error.("Ellipse #{field} must be positive") unless value.positive?
+          value
+        end
+
+        @position = Tuple[Point, position]
+        @rotation = Real[:rotation, rotation]
+      end
+
+      # Rebuilds an ellipse from rounded canonical fields.
+      # @param precision [Integer, nil] decimal precision, or nil for the current function default
+      # @return [Sevgi::Geometry::Ellipse, Sevgi::Geometry::Circle]
+      # @raise [Sevgi::Geometry::Error] when rounding makes a radius zero
+      # @raise [Sevgi::ArgumentError] when precision is invalid
+      def approx(precision = nil)
+        rebuild(
+          F.approx(rx, precision),
+          F.approx(ry, precision),
+          position.approx(precision),
+          F.approx(rotation, precision)
+        )
+      end
+
+      # Selects a finite, directed arc on this ellipse.
+      # @param starting_angle [Numeric] local starting parameter angle in degrees
+      # @param extent [Numeric] signed angular extent strictly between -360 and 360 degrees
+      # @return [Sevgi::Geometry::Arc]
+      # @raise [Sevgi::Geometry::Error] when angles are invalid
+      def arc(extent:, starting_angle: 0)
+        parent = is_a?(Circle) ? Ellipse[rx, ry, position:] : self
+        Arc.send(:new, parent, starting_angle:, extent:)
+      end
+
+      # rubocop:disable Metrics/AbcSize
+
+      # Returns the axis-aligned bounds without display rounding.
+      # @return [Sevgi::Geometry::Rect]
+      def box
+        cosine, sine = F.cos(rotation), F.sin(rotation)
+        dx = ::Math.hypot(rx * cosine, ry * sine)
+        dy = ::Math.hypot(rx * sine, ry * cosine)
+        Rect.from_corners([position.x - dx, position.y - dy], [position.x + dx, position.y + dy])
+      end
+
+      # rubocop:enable Metrics/AbcSize
+
+      # Reports whether the radii are exactly equal.
+      # @return [Boolean]
+      def circular? = rx == ry
+
+      # rubocop:disable Metrics/AbcSize
+
+      # Draws an SVG ellipse using original geometric values.
+      # @param node [Object] graphics node receiving the element
+      # @param attributes [Hash] SVG attributes, including an optional outer transform
+      # @return [Object] graphics command result
+      def draw(node, **attributes)
+        unless rotation.zero?
+          transform = "rotate(#{rotation} #{position.x} #{position.y})"
+          attributes = attributes.merge(transform: [attributes[:transform], transform].compact.join(" "))
+        end
+
+        node.ellipse(cx: position.x, cy: position.y, rx:, ry:, **attributes)
+      end
+
+      # rubocop:enable Metrics/AbcSize
+
+      # Reports whether the ellipse has zero angular extent. A complete ellipse is never empty.
+      # @return [Boolean]
+      def empty? = false
+
+      # Returns the complete quadratic carrier.
+      # @return [Sevgi::Geometry::Equation::Quadratic]
+      def equation = @equation ||= Equation.quadratic(*coefficients, origin: position)
+
+      # Returns the immutable collection containing the complete carrier.
+      # @return [Array<Sevgi::Geometry::Equation::Quadratic>]
+      def equations = @equations ||= [equation].freeze
+
+      # 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]
+        local = local(point)
+        ::Math.hypot(local.x / rx, local.y / ry) < 1.0 || on?(point)
+      end
+
+      # Returns the perimeter with thread-independent numerical accuracy.
+      # @return [Float]
+      # @raise [Sevgi::Geometry::Error] when length is not finite or integration cannot meet its error target
+      def length = @length ||= arc_length(0, 360)
+
+      # Reports whether a point matches its radial boundary reference at the current coordinate precision.
+      # @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]
+        point != position && point.eq?(self.point(parameter(point)))
+      end
+
+      # Returns the closed boundary length.
+      # @return [Float]
+      def perimeter = length
+
+      # Evaluates the boundary at a local parameter angle.
+      # @param angle [Numeric] clockwise local angle in degrees
+      # @return [Sevgi::Geometry::Point]
+      # @raise [Sevgi::Geometry::Error] when angle or the resulting coordinates are not finite
+      def point(angle)
+        angle = Real[:angle, angle] % 360.0
+        Point[rx * F.cos(angle), ry * F.sin(angle)].rotate(rotation).translate(position.x, position.y)
+      end
+
+      # Returns a reflected copy, preserving Circle where applicable.
+      # @param x [Boolean] reflect across the x-axis
+      # @param y [Boolean] reflect across the y-axis
+      # @return [Sevgi::Geometry::Ellipse, Sevgi::Geometry::Circle]
+      # @raise [Sevgi::Geometry::Error] when a flag is not Boolean
+      def reflect(x: true, y: true) = affine(:reflect, x:, y:).first
+
+      # Rotates the center around the origin and the ellipse axes by the same angle.
+      # @param angle [Numeric] clockwise angle in degrees
+      # @return [Sevgi::Geometry::Ellipse, Sevgi::Geometry::Circle]
+      # @raise [Sevgi::Geometry::Error] when the angle or resulting geometry is invalid
+      def rotate(angle)
+        angle = Real[:angle, angle]
+        rebuild(rx, ry, position.rotate(angle), rotation + angle)
+      end
+
+      # rubocop:disable Metrics/AbcSize
+
+      # Scales the ellipse from the origin. Unequal factors can widen Circle to Ellipse.
+      # @param sx [Numeric] x scale factor
+      # @param sy [Numeric, Sevgi::Undefined] y factor, defaulting to sx
+      # @return [Sevgi::Geometry::Ellipse, Sevgi::Geometry::Circle]
+      # @raise [Sevgi::Geometry::Error] when the transform is singular or the resulting geometry is invalid
+      def scale(sx, sy = Undefined)
+        sx, sy = Real[:sx, sx], Real[:sy, Undefined.default(sy, sx)]
+        return affine(:scale, sx, sy).first unless sx == sy
+
+        rebuild(rx * sx.abs, ry * sy.abs, position.scale(sx, sy), rotation + (sx.negative? ? 180 : 0))
+      end
+
+      # rubocop:enable Metrics/AbcSize
+
+      # Skews the ellipse from the origin.
+      # @param ax [Numeric] x-axis skew angle in degrees
+      # @param ay [Numeric, Sevgi::Undefined] y-axis angle, defaulting to ax
+      # @return [Sevgi::Geometry::Ellipse, Sevgi::Geometry::Circle]
+      # @raise [Sevgi::Geometry::Error] when the transform is singular or the resulting geometry is invalid
+      def skew(ax, ay = Undefined) = affine(:skew, ax, ay).first
+
+      # Skews the ellipse along x.
+      # @param angle [Numeric] skew angle in degrees
+      # @return [Sevgi::Geometry::Ellipse, Sevgi::Geometry::Circle]
+      # @raise [Sevgi::Geometry::Error] when the angle or resulting geometry is invalid
+      def skew_x(angle) = affine(:skew_x, angle).first
+
+      # Skews the ellipse along y.
+      # @param angle [Numeric] skew angle in degrees
+      # @return [Sevgi::Geometry::Ellipse, Sevgi::Geometry::Circle]
+      # @raise [Sevgi::Geometry::Error] when the angle or resulting geometry is invalid
+      def skew_y(angle) = affine(:skew_y, angle).first
+
+      # Returns a translated copy.
+      # @param dx [Numeric] x offset
+      # @param dy [Numeric, Sevgi::Undefined] y offset, defaulting to dx
+      # @return [Sevgi::Geometry::Ellipse, Sevgi::Geometry::Circle]
+      # @raise [Sevgi::Geometry::Error] when offsets or the resulting center are invalid
+      def translate(dx, dy = Undefined) = rebuild(rx, ry, position.translate(dx, dy), rotation)
+
+      alias center position
+
+      private
+
+      def affine(...) = Affine.new(self).transform(...)
+
+      def arc_length(starting_angle, extent)
+        return Real[:length, rx * F.to_radians(extent.abs)] if circular?
+
+        Length.new(rx, ry).integrate(starting_angle, extent)
+      end
+
+      # rubocop:disable-next Metrics/AbcSize
+      def coefficients
+        cosine, sine = F.cos(rotation), F.sin(rotation)
+        a = ((cosine / rx) ** 2) + ((sine / ry) ** 2)
+        b = 2 * cosine * sine * (((1.0 / rx) ** 2) - ((1.0 / ry) ** 2))
+        c = ((sine / rx) ** 2) + ((cosine / ry) ** 2)
+        [a, b, c, 0, 0, -1]
+      end
+
+      # rubocop:disable-next Metrics/AbcSize
+      def extrema
+        cosine, sine = F.cos(rotation), F.sin(rotation)
+        x = F.atan2(-ry * sine, rx * cosine)
+        y = F.atan2(ry * cosine, rx * sine)
+        [x, x + 180, y, y + 180]
+      end
+
+      def local(point) = point.translate(-position.x, -position.y).rotate(-rotation)
+
+      def parameter(point)
+        point = local(point)
+        F.to_degrees(::Math.atan2(point.y / ry, point.x / rx))
+      end
+
+      def rebuild(rx, ry, position, rotation)
+        return Circle[rx, position:] if is_a?(Circle) && rx == ry
+
+        Ellipse[rx, ry, position:, rotation:]
+      end
+
+      def state = [position, rx, ry, rotation]
+
+      require_relative "ellipse/affine"
+      require_relative "ellipse/length"
+    end
+
+    # rubocop:enable Metrics/ClassLength
+  end
+end

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

@@ -7,7 +7,41 @@ 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
+    # @!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 finite trace with opposite traversal.
+    #   @return [Sevgi::Geometry::Line]
+    # @!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 +49,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,41 +68,37 @@ 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]
       def angle = head.angle
 
-      # Returns the ending point.
-      # @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)
-
-      # Returns the starting point.
-      # @return [Sevgi::Geometry::Point]
-      def starting = points.first
+      def right?(point) = F.gt?(side(point), 0.0)
 
       # 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, **)
 
+      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 +110,25 @@ 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 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,132 @@ 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.x, a.y, b.x, b.y])
+
+        Error.("Parallelogram sides must be non-degenerate opposite pairs") unless valid
+      end
+
+      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