sevgi-geometry 0.95.0 → 1.0.0

data/lib/sevgi/geometry/element.rb

@@ -2,35 +2,43 @@
 
 module Sevgi
   module Geometry
-    # Base class for geometric elements.
+    # Abstract base class for positioned geometry values.
+    #
+    # Construct concrete shapes through their class factories. Element
+    # operations return new values, and {#box} supplies the axis-aligned bounds
+    # used by alignment and tiling helpers.
     class Element
+      private_class_method :new
+
       # @overload lined(size = Undefined, open: false)
       #   Builds a lined element subclass.
+      #   Instances expose total path `length`. Closed classes also expose `perimeter`.
       #   @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(...)
-
-      private_class_method :arced
+      #   @raise [Sevgi::Geometry::Error] when size is not Undefined or a positive Integer, or open is not Boolean
+      # @example Define a custom two-segment open shape
+      #   Path = Sevgi::Geometry::Element.lined(2, open: true)
+      #   Path.([0, 0], [1, 0], [1, 1])
+      def self.lined(...) = Lined.send(:build, ...)
 
       # Core API
 
       # Returns a copy moved to a point and optional offset.
+      # @example Position a copy without mutating the source
+      #   source = Sevgi::Geometry::Rect[8, 4, position: [1, 2]]
+      #   moved = source.at([10, 20], dx: 2)
+      #   source.position.deconstruct # => [1.0, 2.0]
+      #   moved.position.deconstruct  # => [12.0, 20.0]
       # @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
+      # @raise [Sevgi::Geometry::Error] when point or an offset cannot be coerced to finite geometry values
       def at(point = nil, dx: 0, dy: 0)
         point = point ? Tuple[Point, point] : position
+        dx = Real[:dx, dx]
+        dy = Real[:dy, dy]
 
         translate(
           (point.x - position.x) + dx,
@@ -44,7 +52,12 @@ module Sevgi
       # @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.
+      # Reports whether the element boundary forms a closed path.
+      # @return [Boolean]
+      def closed? = self.class.send(:close?)
+
+      # Returns carrier equations for candidate boundary intersections.
+      # A finite element can represent only part of each carrier.
       # @abstract Subclasses implement element-specific equations.
       # @return [Array<Sevgi::Geometry::Equation>]
       # @raise [Sevgi::PanicError] when a subclass does not implement equations
@@ -55,6 +68,29 @@ module Sevgi
       # @return [Boolean]
       def ignorable?(precision: nil) = F.zero?(box.width, precision:) && F.zero?(box.height, precision:)
 
+      # Intersects the element boundary with an equation.
+      #
+      # Precision controls boundary membership, returned-coordinate rounding, and duplicate collapse.
+      # A nil precision uses the current thread's function precision for all three stages.
+      # @example Intersect a rectangle with a vertical line
+      #   rect = Sevgi::Geometry::Rect[8, 4]
+      #   axis = Sevgi::Geometry::Equation.vertical(3)
+      #   rect.intersection(axis).map(&:deconstruct) # => [[3.0, 0.0], [3.0, 4.0]]
+      # @param equation [Sevgi::Geometry::Equation] equation to intersect with
+      # @param precision [Integer, nil] coordinate 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)
+        Error.("Must be an equation: #{equation}") unless equation.is_a?(Equation)
+
+        points = equations.flat_map do |candidate|
+          equation.intersect(candidate).select { |point| boundary_point?(point, precision) }
+        end
+
+        points.map { |point| point.approx(precision) }.uniq
+      end
+
       # Returns the element position.
       # @abstract Subclasses implement element-specific positioning.
       # @return [Sevgi::Geometry::Point]
@@ -69,18 +105,54 @@ module Sevgi
       # @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
+      def boundary_point?(point, precision)
+        return on?(point) if precision.nil?
+
+        F.with_precision(precision) { on?(point) }
+      end
+
+      private :boundary_point?
+
       # Element whose boundary is represented by straight segments.
+      #
+      # The same path is available as immutable {#points}, {#segments}, and
+      # {#lines} collections. {#vertices} omits the repeated closing point from
+      # closed shapes. Open paths have the same values in `vertices` and `points`.
+      # Only closed shapes have a filled interior, so `inside?` on an open path
+      # is equivalent to testing its boundary.
+      # @example Inspect path and geometric views
+      #   rect = Sevgi::Geometry::Rect[8, 4]
+      #   rect.vertices.size # => 4
+      #   rect.points.size   # => 5
+      #   rect.segments.size # => 4
+      #   rect.lines.size    # => 4
+      # @see Sevgi::Geometry::Operation.sweep
       class Lined < self
         # Open lined element base class.
+        # @api private
         Open = Class.new(self) do
+          # Returns the first point in the directed path.
+          # @return [Sevgi::Geometry::Point]
+          def starting = points.first
+
+          # Returns the last point in the directed path.
+          # @return [Sevgi::Geometry::Point]
+          def ending = points.last
+
+          # Returns the same trace with opposite traversal.
+          # @return [Sevgi::Geometry::Element::Lined]
+          def reverse = self.class.send(:new_by_points!, *points.reverse)
+
           # 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(",") }, **)
+
+          private :draw!
         end
 
         # Closed lined element base class.
+        # @api private
         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
@@ -88,126 +160,163 @@ module Sevgi
           # @raise [Sevgi::Geometry::Error] when any point cannot be coerced
           def self.new_by_points(*points) = super(*points, points.first)
 
+          # Returns the closed path perimeter.
+          # @return [Float]
+          def perimeter = length
+
           # 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(",") }, **)
+
+          private :draw!
+
+          private_class_method :new_by_points
         end
 
         # Class methods
 
         # Point shortcut names generated for fixed-size lined elements.
+        # @api private
         SHORTCUTS = ("A".."Z").to_a.freeze
+        private_constant :Close, :Open, :SHORTCUTS
+
+        class << self
+          private
+
+          # 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
+          # @raise [Sevgi::Geometry::Error] when size is not Undefined or a positive Integer, or open is not Boolean
+          # @api private
+          def build(size = Undefined, open: false)
+            validate_factory(size, open)
+
+            klass = Class.new(open ? Open : Close)
+            klass.define_singleton_method(:close?) { !open }
+            klass.define_singleton_method(:poly?) { size.equal?(Undefined) }
+            klass.define_singleton_method(:size) { size }
+            define_shortcuts(klass, size, open:) unless size.equal?(Undefined)
+            klass.public_class_method(:[], :call, :from_points, :from_segments)
+            klass.private_class_method(:close?, :poly?, :size)
+            klass
+          end
 
-        # 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 }
-
-            define_singleton_method(:open?) { open }
-
-            define_singleton_method(:poly?) { size == Undefined }
-
-            define_singleton_method(:size) { size }
+          def validate_factory(size, open)
+            unless size.equal?(Undefined) || (size.is_a?(::Integer) && size.positive?)
+              Error.("Lined segment count must be a positive Integer or Undefined")
+            end
 
-            Lined.send(:define_shortcuts, self, size, open:) unless size == Undefined
+            Error.("Lined open flag must be Boolean") unless open.equal?(true) || open.equal?(false)
           end
-        end
 
-        # @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]
+          # @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
+          # @api private
+          def [](...) = new_by_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
+          # @api private
+          def call(...) = new_by_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
+          # @api private
+          def from_points(...) = call(...)
+
+          # @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
+          # @api private
+          def from_segments(*segments, position: Origin) = self[*segments, position:]
+
+          def affine(*points) = new_by_points!(*points)
+
+          def approximate(*points)
+            new_by_points!(*points)
+          rescue Error
+            (close? ? Polygon : Polyline).send(:new_by_points!, *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]
-            @segments = Tuples[Segment, *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
+          # @api private
+          def 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
+          # @api private
+          def new_by_points!(*points)
+            new do
+              @points = Tuples[Point, *points]
+            end
           end
-        end
 
-        private_class_method(:new)
+          # 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
+          # @api private
+          def new_by_segments(*segments, position: Origin)
+            new do
+              @position = Tuple[Point, position]
+              @segments = Tuples[Segment, *segments]
+            end
+          end
 
-        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?
+          def define_line_shortcuts(klass, point_names, closing:)
+            line_names = point_names.each_cons(2).map(&:join)
+            line_names << "#{point_names.last}#{point_names.first}" if closing
 
-          line_names.each_with_index do |name, i|
-            klass.define_method(name) { lines[i] or Error.("No such line: #{name}") }
+            line_names.each_with_index do |name, i|
+              klass.define_method(name) { lines[i] or Error.("No such line: #{name}") }
+            end
           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}") }
+          def 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
-        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:)
+          def 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, closing: !open && point_names.size == size)
+          end
         end
 
-        private_class_method :define_line_shortcuts, :define_point_shortcuts, :define_shortcuts
+        private_class_method :new
 
         # Creates a lined element from a geometry-definition block.
         # @yield evaluates point or segment definitions in the new element
         # @yieldreturn [Object] ignored block result
         # @return [void]
         # @raise [Sevgi::Geometry::Error] when the block is absent or defines inconsistent geometry
+        # @api private
         def initialize(&block)
           super()
 
@@ -220,18 +329,20 @@ module Sevgi
           freeze_geometry!
 
           sanitize
+          validate_geometry!
         end
 
         # Core methods
 
-        # Returns an element with approximate points and segments.
+        # Returns an element rebuilt from rounded boundary points.
+        #
+        # Segments are derived from the rounded points so both representations describe the same path. When rounding
+        # breaks a concrete shape invariant, the result widens to a less specific Rect, Polygon, or Polyline rather than
+        # retaining a misleading concrete class.
+        # @param precision [Integer, nil] decimal precision, or nil for the current function default
         # @return [Sevgi::Geometry::Element::Lined]
-        def approx
-          points, segments = points(true), segments(true)
-          self.class.send(:new) do
-            @points, @segments = points, segments
-          end
-        end
+        # @raise [Sevgi::ArgumentError] when precision is invalid
+        def approx(precision = nil) = self.class.send(:approximate, *rounded_points(precision))
 
         # @overload draw(node, **attributes)
         #   Draws an approximate element into a graphics node.
@@ -239,14 +350,24 @@ module Sevgi
         #   @param attributes [Hash] drawing attributes
         #   @return [Object] graphics node command result
         def draw(...)
-          approx.draw!(...)
+          approx.send(:draw!, ...)
         end
 
-        # Returns immutable element points.
+        # Returns immutable element points in path order.
+        # Closed elements repeat the first vertex at the end.
         # @param approximate [Boolean] true to round points with the current function precision
         # @return [Array<Sevgi::Geometry::Point>] frozen point collection
         def points(approximate = false)
-          approximate ? @points.map(&:approx).freeze : @points
+          approximate ? rounded_points(nil) : @points
+        end
+
+        # Returns immutable geometric vertices in path order.
+        # Closed elements omit the repeated closing point. Open elements return {#points}.
+        # @return [Array<Sevgi::Geometry::Point>] frozen vertex collection
+        def vertices
+          return points unless closed?
+
+          @vertices ||= points[...-1].freeze
         end
 
         # Returns the first point.
@@ -259,53 +380,64 @@ module Sevgi
         # @param approximate [Boolean] true to round segments with the current function precision
         # @return [Array<Sevgi::Geometry::Segment>] frozen segment collection
         def segments(approximate = false)
-          approximate ? @segments.map(&:approx).freeze : @segments
+          approximate ? rounded_segments(nil) : @segments
         end
 
         # Affinity methods
 
+        # Affine operations preserve a shape class while its semantic invariant still holds. Axis-aligned Rect and
+        # Square instances widen to Rect or Parallelogram when rotation, skew, or unequal scaling changes that category.
+
         # @!parse
         #   # Returns an element reflected across the selected axes.
         #   # @param x [Boolean] reflect across the x-axis
         #   # @param y [Boolean] reflect across the y-axis
         #   # @return [Sevgi::Geometry::Element::Lined]
+        #   # @raise [Sevgi::Geometry::Error] when a flag is not Boolean
         #   def reflect(x: true, y: true); end
         #
         #   # Returns an element rotated around the origin.
         #   # @param a [Numeric] clockwise angle in degrees
         #   # @return [Sevgi::Geometry::Element::Lined]
+        #   # @raise [Sevgi::Geometry::Error] when angle is not a finite real number
         #   def rotate(a); end
         #
         #   # Returns an element scaled from the origin.
         #   # @param sx [Numeric] x scale factor
         #   # @param sy [Numeric, Sevgi::Undefined] y scale factor, defaulting to sx
         #   # @return [Sevgi::Geometry::Element::Lined]
+        #   # @raise [Sevgi::Geometry::Error] when a scale is not a finite real number
         #   def scale(sx, sy = Undefined); end
         #
         #   # Returns an element skewed from the origin.
         #   # @param ax [Numeric] x-axis skew angle in degrees
         #   # @param ay [Numeric, Sevgi::Undefined] y-axis skew angle in degrees, defaulting to ax
         #   # @return [Sevgi::Geometry::Element::Lined]
+        #   # @raise [Sevgi::Geometry::Error] when an angle is not a finite real number
         #   def skew(ax, ay = Undefined); end
         #
         #   # Returns an element skewed along x.
         #   # @param a [Numeric] skew angle in degrees
         #   # @return [Sevgi::Geometry::Element::Lined]
+        #   # @raise [Sevgi::Geometry::Error] when angle is not a finite real number
         #   def skew_x(a); end
         #
         #   # Returns an element skewed along y.
         #   # @param a [Numeric] skew angle in degrees
         #   # @return [Sevgi::Geometry::Element::Lined]
+        #   # @raise [Sevgi::Geometry::Error] when angle is not a finite real number
         #   def skew_y(a); end
         #
         #   # Returns an element translated by offset.
         #   # @param dx [Numeric] x offset
         #   # @param dy [Numeric, Sevgi::Undefined] y offset, defaulting to dx
         #   # @return [Sevgi::Geometry::Element::Lined]
+        #   # @raise [Sevgi::Geometry::Error] when an offset is not a finite real number
         #   def translate(dx, dy = Undefined); end
-        Geometry::Affinity.instance_methods.each do |transform|
+        Affinity.public_instance_methods(false).each do |transform|
           define_method(transform) do |*args, **kwargs, &block|
-            self.class.new_by_points!(*points.map { it.public_send(transform, *args, **kwargs, &block) })
+            transformed = points.map { it.public_send(transform, *args, **kwargs, &block) }
+            self.class.send(:affine, *transformed)
           end
         end
 
@@ -338,32 +470,13 @@ module Sevgi
         # @return [Array<Sevgi::Geometry::Equation::Linear>] frozen equation collection
         def equations = @equations ||= lines.map(&:equation).freeze
 
-        # Intersects the element boundary with an equation.
-        #
-        # Boundary membership is tested on unrounded candidate points. `precision:`
-        # only rounds returned coordinates and controls duplicate collapse after
-        # membership has been accepted. When `precision` is nil, returned points use
-        # the current function precision.
-        # @param equation [Sevgi::Geometry::Equation] equation to intersect with
-        # @param precision [Integer, nil] decimal precision for returned points, 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)
-          points = equations.flat_map do |candidate|
-            equation.intersect(candidate).select { |point| boundary_point?(point, precision) }
-          end
-
-          points.map { |point| point.approx(precision) }.uniq
-        end
-
         # 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 [](i) = lines[i].tap { |line| Error.("No line exists for index: #{i}") unless line }
 
         # Returns the bounding rectangle.
         # @return [Sevgi::Geometry::Rect]
@@ -373,26 +486,31 @@ module Sevgi
         # @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 }
+        def call(i) = points[i].tap { Error.("No point exists for index: #{i}") unless it }
 
         # Returns the first segment.
         # @return [Sevgi::Geometry::Segment]
         def head = @head ||= segments.first
 
-        # Returns immutable boundary lines derived from segments and points.
+        # Returns immutable boundary lines with the stored endpoints and segments.
         # @return [Array<Sevgi::Geometry::Line>] frozen line collection
         def lines
-          @lines ||= segments
-            .zip(points[...segments.size])
-            .map { |segment, position|
-              segment.line(position)
-            }
+          @lines ||= points
+            .each_cons(2)
+            .zip(segments)
+            .map do |points, segment|
+              # Rebuilding from either view alone loses stored endpoints or input angles.
+              Line.send(:new) do
+                @points = points
+                @segments = [segment]
+              end
+            end
             .freeze
         end
 
-        # Returns the sum of segment lengths.
+        # Returns the total path length.
         # @return [Float]
-        def perimeter = @perimeter ||= segments.sum(&:length)
+        def length = @length ||= segments.sum(&:length)
 
         # Returns the last segment.
         # @return [Sevgi::Geometry::Segment]
@@ -402,15 +520,21 @@ module Sevgi
 
         # Reports whether a point is inside or on the boundary.
         #
-        # Open paths have no filled interior; for them this predicate is true
+        # Open paths have no filled interior. For them this predicate is true
         # only for points on the actual path boundary.
+        # @example Compare closed and open path containment
+        #   rect = Sevgi::Geometry::Rect[8, 4]
+        #   line = Sevgi::Geometry::Line.([0, 0], [8, 0])
+        #   rect.inside?([4, 2]) # => true
+        #   line.inside?([4, 2]) # => false
+        #   line.inside?([4, 0]) # => true
         # @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]
 
-          return on?(point) if self.class.open?
+          return on?(point) unless closed?
 
           on?(point) || pnpoly(points, point)
         end
@@ -433,18 +557,11 @@ module Sevgi
 
         private
 
-        def boundary_point?(point, precision)
-          return on?(point) if precision.nil?
-
-          F.with_precision(precision) { on?(point) }
-        end
-
         def calculate_points_from_segments
           Error.("No segments found") unless segments
 
           [point = position, *segments.map { point = it.ending(point) }].tap do |points|
-            # Perfectionist touch
-            points[-1] = points.first if points.first.eq?(points.last)
+            points[-1] = points.first if closed? && points.first.eq?(points.last)
           end
         end
 
@@ -484,23 +601,62 @@ module Sevgi
         end
         # rubocop:enable Metrics/MethodLength
 
+        def rounded_points(precision)
+          rounded = @points.map { it.approx(precision) }
+          rounded[-1] = rounded.first if closed?
+          rounded.freeze
+        end
+
+        def rounded_segments(precision)
+          rounded_points(precision).each_cons(2).map { Segment.(*it) }.freeze
+        end
+
         def sanitize
-          np = self.class.poly? ? points.size : self.class.size + 1
+          np = self.class.send(:poly?) ? points.size : self.class.send(:size) + 1
           ns = np - 1
 
           Error.("Wrong number of points;  expected #{np} where found #{points.size}") unless points.size == np
           Error.("Wrong number of segments; expected #{ns} where found #{segments.size}") unless segments.size == ns
-          Error.("Element points must form a closed path") if self.class.close? && !points.first.eq?(points.last)
+          return unless closed? && !points.first.eq?(points.last)
+
+          Error.("Element points must form a closed path")
         end
+
+        def validate_geometry! = nil
       end
 
-      # Reserved base for future arced elements.
-      # @api private
+      # Abstract family of circular and elliptical boundary elements.
+      # Arc is open, while Ellipse and Circle have closed boundaries. Concrete values share exact and precision-aware comparisons.
       class Arced < self
+        # Compares canonical fields with coordinate and numeric precision.
+        # @param other [Object] comparison target
+        # @param precision [Integer, nil] decimal precision, or nil for the current function default
+        # @return [Boolean]
+        def eq?(other, precision: nil)
+          other.instance_of?(self.class) &&
+            state.zip(other.send(:state)).all? do |left, right|
+              left.is_a?(::Numeric) ? F.eq?(left, right, precision:) : left.eq?(right, precision:)
+            end
+        end
+
+        # Reports strict equality by concrete class and canonical fields.
+        # @param other [Object] comparison target
+        # @return [Boolean]
+        def eql?(other) = other.instance_of?(self.class) && state == other.send(:state)
+
+        # Returns a hash independent of numeric precision.
+        # @return [Integer]
+        def hash = [self.class, *state].hash
+
+        # Reports whether a point is outside the element.
+        # @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)
+
+        alias == eql?
       end
 
-      private_constant :Arced
-      # rubocop:enable Metrics/ClassLength
     end
 
     require_relative "elements/line"
@@ -509,5 +665,8 @@ module Sevgi
     require_relative "elements/polyline"
     require_relative "elements/rect"
     require_relative "elements/triangle"
+    require_relative "elements/ellipse"
+    require_relative "elements/circle"
+    require_relative "elements/arc"
   end
 end