sevgi-geometry 0.73.2 → 0.94.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9be3893bcfca34cd9d7a2014de7fbb21ba0720e34625c700dcd9dd20b16f1c52
-  data.tar.gz: d9936cd27f1a5360163ef50ca926263b7d913bf3512b14006a504dd5c393d3aa
+  metadata.gz: d61732219fd2a5aec56e466123a5aab75df9e1b25734fe8449a2d4235b8d10b4
+  data.tar.gz: a0ba1edbfaefbcc54912f5fe0e24cea5af13ec834fde5e3147c81fe4ae3a80c2
 SHA512:
-  metadata.gz: 452bdaf29a65ce32032326de0968852cb1449e4faefb5fe3ee24fe6cb8e7ea335d5760264fa08505c6a83f6f763585d9fd4c859b278c6d008ba00be58c7e4b18
-  data.tar.gz: 50f163f2a6d50e2bea7be781a45bba8a1dbdaaaf45a00004b73d8c58ac2306da54cf82a6418696fa11fa49ac47f562857f4b56a81007f0a73244cb9b67079713
+  metadata.gz: cfdf1b5a5e128e678225357e9073282dfc8376ed0547f9dadb00bad1d7c60243b748077912a3b218226a079ba5605ab5c5d9a6f7abe0d0541132dcc0aeca2328
+  data.tar.gz: 37aa84553b62b5d8316923fdfb258de010cafbed34ea3a464a7e5d3134f746acd18e3bb39985a613b64a731d2195246aab755c545345d812a14d141bb8fd2625

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+Sevgi Geometry follows the root Sevgi release notes:
+https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/LICENSE

@@ -0,0 +1,5 @@
+Sevgi Geometry is distributed under the GNU General Public License v3.0 or later.
+
+SPDX-License-Identifier: GPL-3.0-or-later
+
+Full project license: https://github.com/roktas/sevgi/blob/main/LICENSE

data/README.md

@@ -0,0 +1,37 @@
+# Sevgi Geometry
+
+Small geometry primitives and operations for Sevgi drawings.
+
+## Install
+
+```sh
+gem install sevgi-geometry
+```
+
+## Require
+
+```ruby
+require "sevgi/geometry"
+```
+
+## Example
+
+```ruby
+rect = Sevgi::Geometry::Rect[3, 5]
+rect.box.width
+```
+
+## Ruby compatibility
+
+Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4 and the current development Ruby from `.ruby-version`.
+
+## Native prerequisites
+
+None beyond Ruby and this gem's Ruby dependencies.
+
+## Links
+
+- Documentation: https://sevgi.roktas.dev
+- API documentation: https://www.rubydoc.info/gems/sevgi-geometry
+- Source: https://github.com/roktas/sevgi/tree/main/geometry
+- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/lib/sevgi/geometry/element.rb

@@ -2,47 +2,107 @@
 
 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(...)
 
+      private_class_method :arced
+
       # 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 +113,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 +180,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()
 
@@ -98,12 +212,15 @@ module Sevgi
 
           @points ||= calculate_points_from_segments
           @segments ||= calculate_segments_from_points
+          freeze_geometry!
 
           sanitize
         end
 
         # 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,24 +228,76 @@ 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 immutable element points.
+        # @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_approx ||= @points.map(&:approx)) : @points
+          approximate ? @points.map(&:approx).freeze : @points
         end
 
+        # Returns the first point.
+        # @return [Sevgi::Geometry::Point]
         def position
           @position ||= points.first
         end
 
+        # Returns immutable element segments.
+        # @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_approx ||= @segments.map(&:approx)) : @segments
+          approximate ? @segments.map(&:approx).freeze : @segments
         end
 
         # Affinity methods
 
+        # @!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]
+        #   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]
+        #   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]
+        #   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]
+        #   def skew(ax, ay = Undefined); end
+        #
+        #   # Returns an element skewed along x.
+        #   # @param a [Numeric] skew angle in degrees
+        #   # @return [Sevgi::Geometry::Element::Lined]
+        #   def skew_x(a); end
+        #
+        #   # Returns an element skewed along y.
+        #   # @param a [Numeric] skew angle in degrees
+        #   # @return [Sevgi::Geometry::Element::Lined]
+        #   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]
+        #   def translate(dx, dy = Undefined); end
         Geometry::Affinity.instance_methods.each do |transform|
           define_method(transform) do |*args, **kwargs, &block|
             self.class.new_by_points!(*points.map { it.public_send(transform, *args, **kwargs, &block) })
@@ -137,51 +306,123 @@ module Sevgi
 
         # Equality methods
 
-        def eql?(other) = self.class == other.class && points(true) == other.points(true)
+        # Compares element points with optional numeric precision.
+        # @param other [Object] object to compare
+        # @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) &&
+            points.size == other.points.size &&
+            points.zip(other.points).all? { |left, right| left.eq?(right, precision:) }
+        end
+
+        # Reports strict element equality by class and exact points.
+        # @param other [Object] object to compare
+        # @return [Boolean]
+        def eql?(other) = other.instance_of?(self.class) && points == other.points
 
-        def hash = [self.class, *points(true)].hash
+        # Returns a hash compatible with strict equality.
+        # @return [Integer]
+        def hash = [self.class, *points].hash
 
         alias == eql?
 
         # Interaction methods
 
-        def equations = @equations ||= lines.map(&:equation)
-
+        # Returns immutable boundary equations for all lines.
+        # @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)
           equations
-            .map do |candidate|
-              equation.intersect(candidate).map { |point| point.approx(precision) }.select { |point| on?(point) }
-            end
-            .flatten
+            .flat_map { |candidate| equation.intersect(candidate).select { |point| on?(point) } }
+            .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 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 immutable boundary lines derived from segments and points.
+        # @return [Array<Sevgi::Geometry::Line>] frozen line collection
         def lines
-          @lines ||= segments.zip(points[...segments.size]).map { |segment, position|
-            segment.line(position)
-          }
+          @lines ||= segments
+            .zip(points[...segments.size])
+            .map { |segment, position|
+              segment.line(position)
+            }
+            .freeze
         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.
+        #
+        # Open paths have no filled interior; for them this predicate is true
+        # only for points on the actual path 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]
+
+          return on?(point) if self.class.open?
 
-        def on?(point) = lines.any? { it.over?(point) }
+          on?(point) || pnpoly(points, point)
+        end
+
+        # 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
@@ -201,6 +442,11 @@ module Sevgi
           points.each_cons(2).map { Segment.(*it) }
         end
 
+        def freeze_geometry!
+          @points = @points.dup.freeze
+          @segments = @segments.dup.freeze
+        end
+
         # rubocop:disable Metrics/MethodLength
         # https://wrfranklin.org/Research/Short_Notes/pnpoly.html
         def pnpoly(vertices, test)
@@ -236,20 +482,20 @@ module Sevgi
         end
       end
 
+      # Reserved base for future arced elements.
+      # @api private
       class Arced < self
       end
+
+      private_constant :Arced
       # 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/circle"
-    require_relative "elements/curve"
-    require_relative "elements/ellipse"
+    require_relative "elements/triangle"
   end
 end

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

@@ -1,30 +1,86 @@
 # frozen_string_literal: true
 
-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
+      # Returns the clockwise line angle in degrees.
+      # @return [Float]
+      def angle = head.angle
 
-      def_delegators :head, :length, :angle
+      # Returns the ending point.
+      # @return [Sevgi::Geometry::Point]
+      def ending = points.last
 
-      def_delegator :points, :first, :starting
-      def_delegator :points, :last, :ending
+      # Reports whether a point is left of the line equation.
+      # @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)
 
-      def_delegators :equation, :left?, :right?
+      # Returns the line segment length.
+      # @return [Float]
+      def length = head.length
 
-      alias a angle
-      alias l length
+      # Reports whether a point is right of the line equation.
+      # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
+      # @return [Boolean]
+      # @raise [Sevgi::Geometry::Error] when point cannot be coerced
+      def right?(point) = equation.right?(point)
 
-      def draw!(node, **) = node.Cline(x1: position.x, y1: position.y, x2: ending.x, y2: ending.y, **)
+      # Returns the starting point.
+      # @return [Sevgi::Geometry::Point]
+      def starting = points.first
 
-      # TODO: xxx
-      def over?(point) = within_range?(point) && equation.on?(point)
+      # 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, **)
+
+      # 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]
+
+        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