sevgi-geometry 0.73.2 → 0.94.0

data/lib/sevgi/geometry/internal.rb

@@ -2,12 +2,39 @@
 
 module Sevgi
   module Geometry
+    # Validates finite real numeric inputs for geometry primitives.
+    # @api private
+    module Real
+      # Coerces a public numeric value to Float.
+      # @param field [Symbol, String] coordinate or component name
+      # @param value [Object] value to coerce
+      # @return [Float] finite float value
+      # @raise [Sevgi::Geometry::Error] when value is not a finite Numeric
+      def self.[](field, value)
+        unless value.is_a?(::Numeric)
+          Error.("Geometry #{field} must be a finite Numeric: #{value.inspect}")
+        end
+
+        value.to_f.tap do |number|
+          Error.("Geometry #{field} must be finite: #{value.inspect}") unless number.finite?
+        end
+      end
+    end
+
+    private_constant :Real
+
+    # Coerces array-like geometry inputs into typed tuple objects.
+    # @api private
     module Tuple
+      # Coerces an argument into the requested tuple class.
+      # @param klass [Class] tuple class such as {Point} or {Segment}
+      # @param arg [Array<Numeric>, Object] tuple instance or two-element numeric array
+      # @return [Object] tuple instance
+      # @raise [Sevgi::Geometry::Error] when arg cannot be coerced
       def self.[](klass, arg)
         case arg
         when ::Array
-          Error.("Array must have 2 elements: #{arg}", arg) unless arg.size == 2
-          Error.("Must be a numeric array: #{arg}") unless arg.all?(::Numeric)
+          Error.("Array must have 2 elements: #{arg.inspect}") unless arg.size == 2
 
           klass.send(:new, *arg)
         when klass
@@ -20,7 +47,14 @@ module Sevgi
 
     private_constant :Tuple
 
+    # Coerces multiple array-like geometry inputs into typed tuple objects.
+    # @api private
     module Tuples
+      # Coerces arguments into the requested tuple class.
+      # @param klass [Class] tuple class such as {Point} or {Segment}
+      # @param args [Array<Array<Numeric>, Object>] tuple instances or two-element numeric arrays
+      # @return [Array<Object>] tuple instances
+      # @raise [Sevgi::Geometry::Error] when any argument cannot be coerced
       def self.[](klass, *args) = args.map { Tuple[klass, it] }
     end
 

data/lib/sevgi/geometry/operation/align.rb

@@ -3,36 +3,64 @@
 module Sevgi
   module Geometry
     module Operation
+      # Alignment operation implementation.
       module Align
+        extend self
+
+        # Returns an element translated to align with another element.
+        # @param element [Sevgi::Geometry::Element] element to move
+        # @param other [Sevgi::Geometry::Element] reference element
+        # @param alignment [Symbol] one of :center, :left, :right, :top, or :bottom
+        # @return [Sevgi::Geometry::Element] translated element
+        # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when other is not a geometry element
+        # @raise [Sevgi::ArgumentError] when alignment is unknown
         def align(element, other, alignment = :center)
-          alignment(element, other, alignment).apply(element)
+          offset = alignment(element, other, alignment)
+
+          element.translate(offset.x, offset.y)
         end
 
+        # Returns the offset needed to align one element with another.
+        # @param element [Sevgi::Geometry::Element] element to move
+        # @param other [Sevgi::Geometry::Element] reference element
+        # @param alignment [Symbol] one of :center, :left, :right, :top, or :bottom
+        # @return [Sevgi::Geometry::Point] translation offset
+        # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when other is not a geometry element
+        # @raise [Sevgi::ArgumentError] when alignment is unknown
         def alignment(element, other, alignment = :center)
+          OperationInapplicableError.("Not a Geometric Element: #{other}") unless other.is_a?(Element)
+
           this, that = element.box, other.box
 
           case alignment
           when :center
-            Translation[(this.width - that.width) / 2.0, (this.height - that.height) / 2.0]
+            Point[
+              that.position.x + ((that.width - this.width) / 2.0) - this.position.x,
+              that.position.y + ((that.height - this.height) / 2.0) - this.position.y
+            ]
           when :left
-            Translation[this.ne.x - that.ne.x, 0]
+            Point[that.position.x - this.position.x, 0]
           when :right
-            Translation[this.sw.x - that.sw.x, 0]
+            Point[(that.position.x + that.width) - (this.position.x + this.width), 0]
           when :top
-            Translation[0, this.ne.y - that.ne.y]
+            Point[0, that.position.y - this.position.y]
           when :bottom
-            Translation[0, this.sw.y - that.sw.y]
+            Point[0, (that.position.y + that.height) - (this.position.y + this.height)]
           else
             ArgumentError.("No such type of alignment: #{alignment}")
           end
         end
 
-        def applicable?(element)
-          Translation.applicable?(element)
-        end
+        # Reports whether the alignment handler can operate on an element.
+        # @api private
+        # @param element [Object] candidate element
+        # @return [Boolean]
+        def applicable?(element) = element.respond_to?(:translate)
       end
 
       register(Align, :align, :alignment)
+
+      private_constant :Align
     end
   end
 end

data/lib/sevgi/geometry/operation/sweep.rb

@@ -3,13 +3,30 @@
 module Sevgi
   module Geometry
     module Operation
+      # Sweep operation implementation.
       module Sweep
         extend self
 
+        # Default maximum number of sweep iterations.
         LIMIT = 1_000
 
-        def sweep(element, initial:, direction:, step:, limit: LIMIT, &block)
-          equation = Tuple[Point, initial].equation(direction)
+        # Sweeps parallel lines across a lined element in both directions.
+        #
+        # Generated lines are boundary-to-boundary interior spans. A single
+        # sweep position can produce multiple lines for closed concave elements.
+        # @param element [Sevgi::Geometry::Element::Lined] element to intersect
+        # @param initial [Sevgi::Geometry::Point, Array<Numeric>] point on the initial sweep line
+        # @param angle [Numeric] clockwise sweep line angle in degrees
+        # @param step [Numeric] signed distance between sweep lines
+        # @param limit [Integer] maximum iterations per direction
+        # @yield [lines] optional hook receiving the generated lines
+        # @yieldparam lines [Array<Sevgi::Geometry::Line>] generated sweep lines
+        # @yieldreturn [void]
+        # @return [Array<Sevgi::Geometry::Line>] generated sweep lines
+        # @raise [Sevgi::Geometry::Error] when initial cannot be coerced
+        # @raise [Sevgi::Geometry::Operation::OperationError] when iteration reaches the limit
+        def sweep(element, initial:, angle:, step:, limit: LIMIT, &block)
+          equation = Tuple[Point, initial].equation(angle)
 
           [
             *unisweep(element, equation.shift(-step), -step, limit:).reverse,
@@ -19,16 +36,41 @@ module Sevgi
           end
         end
 
-        def sweep!(element, initial:, direction:, step:, limit: LIMIT, &block)
-          sweep(element, initial:, direction:, step:, limit:) do |lines|
+        # Sweeps parallel lines across a lined element and requires at least one result.
+        #
+        # Generated lines are boundary-to-boundary interior spans. A single
+        # sweep position can produce multiple lines for closed concave elements.
+        # @param element [Sevgi::Geometry::Element::Lined] element to intersect
+        # @param initial [Sevgi::Geometry::Point, Array<Numeric>] point on the initial sweep line
+        # @param angle [Numeric] clockwise sweep line angle in degrees
+        # @param step [Numeric] signed distance between sweep lines
+        # @param limit [Integer] maximum iterations per direction
+        # @yield [lines] optional hook receiving the generated lines
+        # @yieldparam lines [Array<Sevgi::Geometry::Line>] generated sweep lines
+        # @yieldreturn [void]
+        # @return [Array<Sevgi::Geometry::Line>] generated sweep lines
+        # @raise [Sevgi::Geometry::Error] when initial cannot be coerced
+        # @raise [Sevgi::Geometry::Operation::OperationError] when no lines are found or iteration reaches the limit
+        def sweep!(element, initial:, angle:, step:, limit: LIMIT, &block)
+          sweep(element, initial:, angle:, step:, limit:) do |lines|
             if lines.empty?
-              OperationError.("No lines found [initial: #{initial}, direction: #{direction} step: #{step}]")
+              OperationError.("No lines found [initial: #{initial}, angle: #{angle} step: #{step}]")
             end
 
             yield(lines) if block
           end
         end
 
+        # Sweeps parallel lines in one signed direction from an equation.
+        #
+        # Generated lines are boundary-to-boundary interior spans. A single
+        # sweep position can produce multiple lines for closed concave elements.
+        # @param element [Sevgi::Geometry::Element::Lined] element to intersect
+        # @param equation [Sevgi::Geometry::Equation] initial sweep equation
+        # @param step [Numeric] signed distance between sweep lines
+        # @param limit [Integer] maximum iterations
+        # @return [Array<Sevgi::Geometry::Line>] generated sweep lines
+        # @raise [Sevgi::Geometry::Operation::OperationError] when iteration reaches the limit
         def unisweep(element, equation, step, limit: LIMIT)
           lines = []
 
@@ -36,9 +78,7 @@ module Sevgi
             points = element.intersection(equation)
             return lines if points.empty?
 
-            if points.size == 2 && !(line = Line.(*points)).ignorable?
-              lines << line
-            end
+            lines.concat(interior_lines(element, equation, points))
 
             equation = equation.shift(step)
           end
@@ -46,12 +86,50 @@ module Sevgi
           OperationError.("Loop limit reached: #{limit}")
         end
 
+        # Reports whether the sweep handler can operate on an element.
+        # @api private
+        # @param element [Object] candidate element
+        # @return [Boolean]
         def applicable?(element)
           element.respond_to?(:intersection)
         end
+
+        private
+
+        def interior_lines(element, equation, points)
+          if points.size == 2
+            line = simple_line(points)
+
+            return line ? [line] : []
+          end
+
+          sorted_points(equation, points).each_cons(2).filter_map do |starting, ending|
+            next unless element.inside?(midpoint(starting, ending))
+
+            simple_line([starting, ending])
+          end
+        end
+
+        def midpoint(starting, ending)
+          Point[(starting.x + ending.x) / 2.0, (starting.y + ending.y) / 2.0]
+        end
+
+        def simple_line(points)
+          line = Line.(*points)
+
+          line unless line.ignorable?
+        end
+
+        def sorted_points(equation, points)
+          points.sort_by do |point|
+            equation.is_a?(Equation::Linear::Vertical) ? [point.y, point.x] : [point.x, point.y]
+          end
+        end
       end
 
       register(Sweep, :sweep, :sweep!, :unisweep)
+
+      private_constant :Sweep
     end
   end
 end

data/lib/sevgi/geometry/operation.rb

@@ -2,14 +2,85 @@
 
 module Sevgi
   module Geometry
+    # Dispatches geometry operations to operation handler modules.
     module Operation
       extend self
 
+      # Raised when an operation starts but cannot complete.
       OperationError = Class.new(Error)
+
+      # Raised when an operation does not apply to the target element.
       OperationInapplicableError = Class.new(Error)
 
+      # @!parse
+      #   class << self
+      #     # Returns an element translated to align with another element.
+      #     # @param element [Sevgi::Geometry::Element] element to move
+      #     # @param other [Sevgi::Geometry::Element] reference element
+      #     # @param alignment [Symbol] one of :center, :left, :right, :top, or :bottom
+      #     # @return [Sevgi::Geometry::Element] translated element
+      #     # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when an argument is not a geometry element
+      #     # @raise [Sevgi::ArgumentError] when alignment is unknown
+      #     def align(element, other, alignment = :center); end
+      #
+      #     # Returns the offset needed to align one element with another.
+      #     # @param element [Sevgi::Geometry::Element] element to move
+      #     # @param other [Sevgi::Geometry::Element] reference element
+      #     # @param alignment [Symbol] one of :center, :left, :right, :top, or :bottom
+      #     # @return [Sevgi::Geometry::Point] translation offset
+      #     # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when an argument is not a geometry element
+      #     # @raise [Sevgi::ArgumentError] when alignment is unknown
+      #     def alignment(element, other, alignment = :center); end
+      #
+      #     # Sweeps parallel lines across a lined element in both directions.
+      #     # @param element [Sevgi::Geometry::Element::Lined] element to intersect
+      #     # @param initial [Sevgi::Geometry::Point, Array<Numeric>] point on the initial sweep line
+      #     # @param angle [Numeric] clockwise sweep line angle in degrees
+      #     # @param step [Numeric] signed distance between sweep lines
+      #     # @param limit [Integer] maximum iterations per direction
+      #     # @yield [lines] optional hook receiving the generated lines
+      #     # @yieldparam lines [Array<Sevgi::Geometry::Line>] generated sweep lines
+      #     # @yieldreturn [void]
+      #     # @return [Array<Sevgi::Geometry::Line>] generated sweep lines
+      #     # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when element is not sweepable
+      #     # @raise [Sevgi::Geometry::Error] when initial cannot be coerced
+      #     # @raise [Sevgi::Geometry::Operation::OperationError] when iteration reaches the limit
+      #     def sweep(element, initial:, angle:, step:, limit: Sweep::LIMIT); end
+      #
+      #     # Sweeps parallel lines across a lined element and requires at least one result.
+      #     # @param element [Sevgi::Geometry::Element::Lined] element to intersect
+      #     # @param initial [Sevgi::Geometry::Point, Array<Numeric>] point on the initial sweep line
+      #     # @param angle [Numeric] clockwise sweep line angle in degrees
+      #     # @param step [Numeric] signed distance between sweep lines
+      #     # @param limit [Integer] maximum iterations per direction
+      #     # @yield [lines] optional hook receiving the generated lines
+      #     # @yieldparam lines [Array<Sevgi::Geometry::Line>] generated sweep lines
+      #     # @yieldreturn [void]
+      #     # @return [Array<Sevgi::Geometry::Line>] generated sweep lines
+      #     # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when element is not sweepable
+      #     # @raise [Sevgi::Geometry::Error] when initial cannot be coerced
+      #     # @raise [Sevgi::Geometry::Operation::OperationError] when no lines are found or iteration reaches the limit
+      #     def sweep!(element, initial:, angle:, step:, limit: Sweep::LIMIT); end
+      #
+      #     # Sweeps parallel lines in one signed direction from an equation.
+      #     # @param element [Sevgi::Geometry::Element::Lined] element to intersect
+      #     # @param equation [Sevgi::Geometry::Equation] initial sweep equation
+      #     # @param step [Numeric] signed distance between sweep lines
+      #     # @param limit [Integer] maximum iterations
+      #     # @return [Array<Sevgi::Geometry::Line>] generated sweep lines
+      #     # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when element is not sweepable
+      #     # @raise [Sevgi::Geometry::Operation::OperationError] when iteration reaches the limit
+      #     def unisweep(element, equation, step, limit: Sweep::LIMIT); end
+      #   end
+      # Registers one or more public operation methods.
+      # @api private
+      # @param handler [Module] operation handler module
+      # @param operations [Array<Symbol>] operation method names
+      # @return [Array<Symbol>] registered operation names
       def register(handler, *operations) = operations.each { |operation| def_operation(operation, handler) }
 
+      private :register
+
       private
 
       def def_operation(operation, handler)

data/lib/sevgi/geometry/point.rb

@@ -2,80 +2,178 @@
 
 module Sevgi
   module Geometry
+    # Affine transforms shared by immutable geometry tuples.
     module Affinity
+      # Reflects a point across the selected axes.
+      #
+      # `x:` controls reflection across the x-axis, which negates y. `y:`
+      # controls reflection across the y-axis, which negates x.
+      # @param x [Boolean] reflect across the x-axis
+      # @param y [Boolean] reflect across the y-axis
+      # @return [Sevgi::Geometry::Point]
       def reflect(x: true, y: true) = with(x: (y ? -1 : 1) * self.x(), y: (x ? -1 : 1) * self.y())
 
-      def reflect_x = with(y: -y)
-
-      def reflect_y = with(x: -x)
-
+      # Rotates a point around the origin using screen-space degrees.
+      # @param a [Numeric] clockwise angle in degrees
+      # @return [Sevgi::Geometry::Point]
       def rotate(a) = with(x: (x * F.cos(a)) - (y * F.sin(a)), y: (x * F.sin(a)) + (y * F.cos(a)))
 
+      # Scales a point from the origin.
+      # @param sx [Numeric] x scale factor
+      # @param sy [Numeric, Sevgi::Undefined] y scale factor, defaulting to sx
+      # @return [Sevgi::Geometry::Point]
       def scale(sx, sy = Undefined) = with(x: sx * x, y: Undefined.default(sy, sx) * y)
 
-      def skew(ax, ay = Undefined) = with(x: x + (y * F.tan(ax)), y: y + (x * F.tan(Undefined(ay, ax))))
+      # Skews a point 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::Point]
+      def skew(ax, ay = Undefined) = with(x: x + (y * F.tan(ax)), y: y + (x * F.tan(Undefined.default(ay, ax))))
 
-      def skew_x(a) = with(x: x + (y * f.tan(a)))
+      # Skews a point along x.
+      # @param a [Numeric] skew angle in degrees
+      # @return [Sevgi::Geometry::Point]
+      def skew_x(a) = with(x: x + (y * F.tan(a)))
 
+      # Skews a point along y.
+      # @param a [Numeric] skew angle in degrees
+      # @return [Sevgi::Geometry::Point]
       def skew_y(a) = with(y: y + (x * F.tan(a)))
 
+      # Translates a point.
+      # @param dx [Numeric] x offset
+      # @param dy [Numeric, Sevgi::Undefined] y offset, defaulting to dx
+      # @return [Sevgi::Geometry::Point]
       def translate(dx, dy = Undefined) = with(x: x + dx, y: y + Undefined.default(dy, dx))
     end
 
+    # Immutable point in SVG/screen coordinates.
+    #
+    # Use `Point[x, y]` to create a point from two coordinates.
     Point = Data.define(:x, :y) do
       include Comparable
       include Affinity
 
+      # @!attribute [r] x
+      #   @return [Float] x coordinate
+      # @!attribute [r] y
+      #   @return [Float] y coordinate
+
+      # Returns the screen-space angle from one point to another.
+      # @param starting [Sevgi::Geometry::Point, Array<Numeric>] start point
+      # @param ending [Sevgi::Geometry::Point, Array<Numeric>] end point
+      # @return [Float] clockwise angle in degrees
+      # @raise [Sevgi::Geometry::Error] when either point cannot be coerced
       def self.angle(starting, ending)
         starting, ending = Tuples[Point, starting, ending]
         F.atan2(ending.y - starting.y, ending.x - starting.x)
       end
 
+      # Compares two points with optional numeric precision.
+      # @param this [Sevgi::Geometry::Point, Array<Numeric>] first point
+      # @param that [Sevgi::Geometry::Point, Array<Numeric>] second point
+      # @param precision [Integer, nil] decimal precision, or nil for the current function default
+      # @return [Boolean]
+      # @raise [Sevgi::Geometry::Error] when either point cannot be coerced
       def self.eq?(this, that, precision: nil)
         this, that = Tuples[self, this, that]
         F.eq?(this.x, that.x, precision:) && F.eq?(this.y, that.y, precision:)
       end
 
+      # Returns the Euclidean distance between two points.
+      # @param starting [Sevgi::Geometry::Point, Array<Numeric>] start point
+      # @param ending [Sevgi::Geometry::Point, Array<Numeric>] end point
+      # @return [Float]
+      # @raise [Sevgi::Geometry::Error] when either point cannot be coerced
       def self.length(starting, ending)
         starting, ending = Tuples[Point, starting, ending]
         ::Math.sqrt(((starting.y - ending.y) ** 2) + ((starting.x - ending.x) ** 2))
       end
 
+      # Returns the origin point.
+      # @return [Sevgi::Geometry::Point]
       def self.origin
         new(x: 0.0, y: 0.0)
       end
 
-      def initialize(x:, y:) = super(x: x.to_f, y: y.to_f)
-
+      # Creates a point.
+      # @param x [Numeric] x coordinate
+      # @param y [Numeric] y coordinate
+      # @return [void]
+      # @raise [Sevgi::Geometry::Error] when a coordinate is not a finite Numeric
+      def initialize(x:, y:) = super(x: Real[:x, x], y: Real[:y, y])
+
+      # Compares points by x, then y.
+      # @param other [Sevgi::Geometry::Point, Array<Numeric>] point to compare
+      # @return [Integer, nil]
+      # @raise [Sevgi::Geometry::Error] when other cannot be coerced
       def <=>(other) = (other = Tuple[Point, other]).nan? || nan? ? nil : deconstruct <=> other.deconstruct
 
+      # Reports whether this point is at or above another point in screen coordinates.
+      # @param other [Sevgi::Geometry::Point, Array<Numeric>] point to compare
+      # @return [Boolean]
+      # @raise [Sevgi::Geometry::Error] when other cannot be coerced
       def above?(other) = y <= Tuple[Point, other].y
 
+      # Returns a point rounded to precision.
+      # @param precision [Integer, nil] decimal precision, or nil for the current function default
+      # @return [Sevgi::Geometry::Point]
       def approx(precision = nil) = with(x: F.approx(x, precision), y: F.approx(y, precision))
 
+      # Reports whether this point is at or below another point in screen coordinates.
+      # @param other [Sevgi::Geometry::Point, Array<Numeric>] point to compare
+      # @return [Boolean]
+      # @raise [Sevgi::Geometry::Error] when other cannot be coerced
       def below?(other) = y >= Tuple[Point, other].y
 
+      # Compares this point with optional numeric precision.
+      # @param other [Sevgi::Geometry::Point, Array<Numeric>] point to compare
+      # @param precision [Integer, nil] decimal precision, or nil for the current function default
+      # @return [Boolean]
+      # @raise [Sevgi::Geometry::Error] when other cannot be coerced
       def eq?(other, precision: nil) = self.class.eq?(self, other, precision:)
 
+      # Reports strict point equality.
+      # @param other [Object] object to compare
+      # @return [Boolean]
       def eql?(other) = self.class == other.class && deconstruct == other.deconstruct
 
+      # Returns a hash compatible with strict equality.
+      # @return [Integer]
       def hash = [self.class, *deconstruct].hash
 
+      # Reports whether any coordinate is infinite.
+      # @return [Boolean]
       def infinite? = deconstruct.any?(&:infinite?)
 
+      # Reports whether this point is at or left of another point.
+      # @param other [Sevgi::Geometry::Point, Array<Numeric>] point to compare
+      # @return [Boolean]
+      # @raise [Sevgi::Geometry::Error] when other cannot be coerced
       def left?(other) = x <= Tuple[Point, other].x
 
+      # Reports whether any coordinate is NaN.
+      # @return [Boolean]
       def nan? = deconstruct.any?(&:nan?)
 
+      # Reports whether this point is at or right of another point.
+      # @param other [Sevgi::Geometry::Point, Array<Numeric>] point to compare
+      # @return [Boolean]
+      # @raise [Sevgi::Geometry::Error] when other cannot be coerced
       def right?(other) = x >= Tuple[Point, other].x
 
+      # Formats point coordinates for SVG coordinate-list attributes.
+      # @return [String]
       def to_cs = "#{F.approx(x)},#{F.approx(y)}"
 
+      # Formats the point for display.
+      # @return [String]
       def to_s = "(#{to_cs})"
 
       alias_method :==, :eql?
     end
 
+    # Origin point in SVG/screen coordinates.
     Origin = Point.origin
   end
 end