sevgi-geometry 0.95.0 → 1.0.0

data/lib/sevgi/geometry/predicate.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Geometry
+    # Internal helpers shared by public geometry predicates.
+    # @api private
+    module Predicate
+      extend self
+
+      def adjacent_overlap?(a, b, c, precision: nil)
+        orientation(a, b, c, precision:).zero? &&
+          (point_on_segment?(c, a, b, precision:) || point_on_segment?(a, b, c, precision:))
+      end
+
+      def adjacent_overlap_in?(vertices, precision: nil)
+        vertices.each_index.any? do |i|
+          adjacent_overlap?(vertices[i - 1], vertices[i], vertices[(i + 1) % vertices.size], precision:)
+        end
+      end
+
+      def between?(value, a, b, precision: nil)
+        minimum, maximum = [a, b].minmax
+        F.ge?(value, minimum, precision:) && F.le?(value, maximum, precision:)
+      end
+
+      def collinear?(points, precision: nil)
+        # ponytail: cubic worst-case comparisons; optimize the maximum triangle area if large sets need faster queries.
+        points.sort_by { [it.x, it.y] }.combination(3).all? do |a, b, c|
+          orientation(a, b, c, precision:).zero?
+        end
+      end
+
+      def convex_turns?(vertices, precision: nil)
+        turns = turn_orientations(vertices, precision:)
+        !turns.empty? && turns.uniq.one?
+      end
+
+      def edges(vertices)
+        vertices.each_index.map { |i| [vertices[i], vertices[(i + 1) % vertices.size]] }
+      end
+
+      def nonadjacent_intersection?(vertices, precision: nil)
+        edges = edges(vertices)
+        # ponytail: quadratic comparisons; use a sweep-line algorithm if large polygons need faster queries.
+        edges.each_index.any? do |i|
+          ((i + 1)...edges.size).any? do |j|
+            !adjacent_indices?(i, j, edges.size) && segments_intersect?(*edges[i], *edges[j], precision:)
+          end
+        end
+      end
+
+      def orientation(a, b, c, precision: nil)
+        cross = Cross[b.x - a.x, b.y - a.y, c.x - a.x, c.y - a.y]
+        return 0 if F.zero?(cross, precision:)
+
+        F.lt?(cross, 0.0, precision:) ? -1 : 1
+      end
+
+      def point_on_segment?(point, a, b, precision: nil)
+        orientation(a, b, point, precision:).zero? &&
+          between?(point.x, a.x, b.x, precision:) &&
+          between?(point.y, a.y, b.y, precision:)
+      end
+
+      def repeated_vertex?(vertices, precision: nil)
+        vertices.each_index.any? do |i|
+          ((i + 1)...vertices.size).any? { |j| Point.eq?(vertices[i], vertices[j], precision:) }
+        end
+      end
+
+      def segments_intersect?(a, b, c, d, precision: nil)
+        first = [a, b]
+        second = [c, d]
+        turns = segment_orientations(*first, *second, precision:)
+
+        proper_intersection?(turns) || boundary_intersection?(first, second, turns, precision:)
+      end
+
+      def simple?(vertices, precision: nil)
+        !repeated_vertex?(vertices, precision:) &&
+          !adjacent_overlap_in?(vertices, precision:) &&
+          !nonadjacent_intersection?(vertices, precision:)
+      end
+
+      private
+
+      def adjacent_indices?(i, j, size) = j == i + 1 || (i.zero? && j == size - 1)
+
+      def boundary_intersection?(first, second, turns, precision: nil)
+        a, b = first
+        c, d = second
+        candidates = [[turns[0], c, a, b], [turns[1], d, a, b], [turns[2], a, c, d], [turns[3], b, c, d]]
+
+        candidates.any? { |turn, point, from, to| turn.zero? && point_on_segment?(point, from, to, precision:) }
+      end
+
+      def proper_intersection?(turns)
+        turns.none?(&:zero?) && turns[0] != turns[1] && turns[2] != turns[3]
+      end
+
+      def segment_orientations(a, b, c, d, precision: nil)
+        [
+          orientation(a, b, c, precision:),
+          orientation(a, b, d, precision:),
+          orientation(c, d, a, precision:),
+          orientation(c, d, b, precision:)
+        ]
+      end
+
+      def turn_orientations(vertices, precision: nil)
+        vertices
+          .each_index
+          .map { |i|
+            orientation(vertices[i], vertices[(i + 1) % vertices.size], vertices[(i + 2) % vertices.size], precision:)
+          }
+          .reject(&:zero?)
+      end
+    end
+
+    private_constant :Predicate
+
+    class Point
+      # Reports whether three or more points lie on one infinite line.
+      #
+      # Every three-point subset must have a cross product that rounds to zero at the selected decimal precision.
+      # The cross-product magnitude is twice the triangle area, not a distance tolerance.
+      # Repeated points are allowed. Input order does not affect the result, and accepted sets have accepted subsets.
+      # Triangle area is invariant under rigid motion, subject to floating-point error near the rounding threshold.
+      # The worst-case number of comparisons is cubic in the point count.
+      # @param points [Array<Sevgi::Geometry::Point, Array<Numeric>>] point-like values
+      # @param precision [Integer, nil] decimal precision, or nil for the current function default
+      # @return [Boolean]
+      # @raise [Sevgi::ArgumentError] when fewer than three points are given or precision is not an Integer or nil
+      # @raise [Sevgi::Geometry::Error] when a point cannot be coerced
+      # @example Test a point set
+      #   Sevgi::Geometry::Point.collinear?([0, 0], [1, 1], [2, 2]) # => true
+      def self.collinear?(*points, precision: nil)
+        ArgumentError.("At least three points required") if points.size < 3
+
+        Predicate.collinear?(Tuples[self, *points], precision:)
+      end
+    end
+
+    class Polygon
+      # Reports whether the polygon boundary has no self-intersection.
+      #
+      # Adjacent edges may meet only at their shared endpoint. Non-adjacent
+      # touches and overlaps make the polygon non-simple.
+      # @param precision [Integer, nil] decimal precision, or nil for the current function default
+      # @return [Boolean]
+      # @raise [Sevgi::ArgumentError] when precision is not an Integer or nil
+      def simple?(precision: nil) = Predicate.simple?(vertices, precision:)
+
+      # Reports whether this is a simple polygon whose non-collinear turns all have one orientation.
+      #
+      # Redundant vertices on straight edges are permitted. Self-intersecting
+      # and fully degenerate polygons are not convex.
+      # @param precision [Integer, nil] decimal precision, or nil for the current function default
+      # @return [Boolean]
+      # @raise [Sevgi::ArgumentError] when precision is not an Integer or nil
+      def convex?(precision: nil)
+        simple?(precision:) && Predicate.convex_turns?(vertices, precision:)
+      end
+
+      # Reports whether this is a simple non-convex polygon.
+      #
+      # Self-intersecting and degenerate polygons are neither convex nor concave.
+      # @param precision [Integer, nil] decimal precision, or nil for the current function default
+      # @return [Boolean]
+      # @raise [Sevgi::ArgumentError] when precision is not an Integer or nil
+      def concave?(precision: nil)
+        simple?(precision:) && !Predicate.convex_turns?(vertices, precision:)
+      end
+    end
+  end
+end

data/lib/sevgi/geometry/segment.rb

@@ -2,10 +2,31 @@
 
 module Sevgi
   module Geometry
-    # Immutable polar segment in SVG/screen coordinates.
+    # Immutable polar displacement in SVG/screen coordinates.
     #
-    # `length` is a distance and `angle` is a clockwise angle in degrees.
-    # Use `Segment[length, angle]` to create a segment from polar components.
+    # A Segment has no position: `length` is a distance and `angle` is a
+    # clockwise direction. Use {#ending} to apply it to a starting point or
+    # {#line} when a placed, finite line is required. `Segment[length, angle]`
+    # starts from polar components. `Segment.(starting, ending)` derives them
+    # from two points.
+    # @example Derive polar components from two points
+    #   segment = Sevgi::Geometry::Segment.([1, 2], [4, 6])
+    #   segment.length # => 5.0
+    #   segment.ending([1, 2]).deconstruct # => [4.0, 6.0]
+    # @example Use a cardinal direction
+    #   Sevgi::Geometry::Segment.upward(3).ending([5, 5]).deconstruct # => [5.0, 2.0]
+    # @see Sevgi::Geometry::Line
+    # @!parse
+    #   class Segment
+    #     # Creates a segment from polar components.
+    #     # @param length [Numeric] non-negative segment length
+    #     # @param angle [Numeric] clockwise angle in degrees
+    #     # @return [Sevgi::Geometry::Segment]
+    #     # @raise [Sevgi::Geometry::Error] when a component is not finite or length is negative
+    #     # @example Create a segment with mathematical notation
+    #     #   Sevgi::Geometry::Segment[5, 30]
+    #     def self.[](length, angle); end
+    #   end
     Segment = Data.define(:length, :angle) do
       include Comparable
 
@@ -56,9 +77,15 @@ module Sevgi
       def self.upward(length) = self[length, -90.0]
 
       class << self
-        # @return [Sevgi::Geometry::Segment]
+        # @overload horizontal(length)
+        #   Returns a rightward segment.
+        #   @param length [Numeric] segment length
+        #   @return [Sevgi::Geometry::Segment]
         alias_method :horizontal, :rightward
-        # @return [Sevgi::Geometry::Segment]
+        # @overload vertical(length)
+        #   Returns a downward segment.
+        #   @param length [Numeric] segment length
+        #   @return [Sevgi::Geometry::Segment]
         alias_method :vertical, :downward
       end
 
@@ -66,14 +93,22 @@ module Sevgi
       # @param length [Numeric] segment length
       # @param angle [Numeric] clockwise angle in degrees
       # @return [void]
-      # @raise [Sevgi::Geometry::Error] when a component is not a finite Numeric
-      def initialize(length:, angle:) = super(length: Real[:length, length], angle: Real[:angle, angle])
+      # @raise [Sevgi::Geometry::Error] when a component is not finite or length is negative
+      def initialize(length:, angle:)
+        length = Real[:length, length]
+        Error.("Segment length cannot be negative") if length.negative?
+
+        super(length:, angle: Real[:angle, angle])
+      end
 
       # Compares segments by length.
-      # @param other [Sevgi::Geometry::Segment, Array<Numeric>] segment to compare
-      # @return [Integer, nil]
-      # @raise [Sevgi::Geometry::Error] when other cannot be coerced
-      def <=>(other) = length <=> Tuple[Segment, other].length
+      # @param other [Object] segment or two-item length/angle array to compare
+      # @return [Integer, nil] comparison result, or nil when other is not a valid segment value
+      def <=>(other)
+        length <=> Tuple[Segment, other].length
+      rescue Error
+        nil
+      end
 
       # Returns a segment rounded to precision.
       # @param precision [Integer, nil] decimal precision, or nil for the current function default
@@ -93,11 +128,13 @@ module Sevgi
       # @raise [Sevgi::Geometry::Error] when other cannot be coerced
       def eq?(other, precision: nil) = self.class.eq?(self, other, precision:)
 
-      # Reports strict segment equality.
+      # Reports exact length-and-direction equality, also used by ==. Ordering through <=> compares length only.
       # @param other [Object] object to compare
       # @return [Boolean]
       def eql?(other) = self.class == other.class && deconstruct == other.deconstruct
 
+      alias_method :==, :eql?
+
       # Returns a hash compatible with strict equality.
       # @return [Integer]
       def hash = [self.class, *deconstruct].hash
@@ -121,7 +158,35 @@ module Sevgi
       def y = length * F.sin(angle)
     end
 
-    # Lightweight polar value used where a plain length/angle tuple is enough.
-    Polar = Data.define(:length, :angle)
+    # Immutable length/angle constraint used when a full segment is not implied.
+    #
+    # @!attribute [r] length
+    #   @return [Float] non-negative target measure
+    # @!attribute [r] angle
+    #   @return [Float] direction used to derive a segment
+    # @!parse
+    #   class LengthAngle
+    #     # Creates a length-and-angle constraint.
+    #     # @param length [Numeric] finite non-negative target width or height
+    #     # @param angle [Numeric] finite direction in degrees
+    #     # @return [Sevgi::Geometry::LengthAngle]
+    #     # @raise [Sevgi::Geometry::Error] when a component is not finite or length is negative
+    #     # @example Create a constraint with mathematical notation
+    #     #   Sevgi::Geometry::LengthAngle[3, 90]
+    #     def self.[](length, angle); end
+    #   end
+    LengthAngle = Data.define(:length, :angle) do
+      # Creates a target-measure constraint.
+      # @param length [Numeric] finite non-negative target width or height
+      # @param angle [Numeric] finite direction in degrees
+      # @return [void]
+      # @raise [Sevgi::Geometry::Error] when a component is not finite or length is negative
+      def initialize(length:, angle:)
+        length = Real[:length, length]
+        Error.("LengthAngle length cannot be negative") if length.negative?
+
+        super(length:, angle: Real[:angle, angle])
+      end
+    end
   end
 end

data/lib/sevgi/geometry/version.rb

@@ -3,6 +3,6 @@
 module Sevgi
   module Geometry
     # Component version.
-    VERSION = "0.95.0"
+    VERSION = "1.0.0"
   end
 end

data/lib/sevgi/geometry.rb

@@ -8,16 +8,40 @@ require_relative "geometry/errors"
 require_relative "geometry/point"
 require_relative "geometry/segment"
 require_relative "geometry/element"
+require_relative "geometry/predicate"
 require_relative "geometry/equation"
 require_relative "geometry/operation"
 
 require_relative "geometry/version"
 
 module Sevgi
-  # Screen-space geometry primitives used by Sevgi layout and drawing helpers.
+  # Immutable screen-space geometry values used by Sevgi layout and drawing helpers.
   #
   # Coordinates follow SVG screen conventions: +x points right, +y points down,
-  # and positive angles turn clockwise.
+  # and positive angles turn clockwise. Constructors accept Point and Segment
+  # objects or their two-number Array forms. Transformations return new values.
+  # They do not mutate their receiver.
+  #
+  # Shape constructors have two complementary notations: `Shape[...]` accepts
+  # dimensions or segments, while `Shape.(...)` accepts points. Named factories
+  # such as `Rect.from_size` and `Rect.from_corners` expose the same distinction
+  # when a call site benefits from spelling it out.
+  #
+  # Trigonometric construction can retain ordinary floating-point noise. Use
+  # `approx` for presentation values and `eq?` for precision-aware comparison.
+  # strict `==` intentionally compares the exact immutable value.
+  #
+  # @example Measure and move a line
+  #   line = Sevgi::Geometry::Line.([0, 0], [3, 4])
+  #   line.length                    #=> 5.0
+  #   line.translate(2, 1).starting #=> Point[2.0, 1.0]
+  # @example Follow SVG screen directions
+  #   origin = Sevgi::Geometry::Point.origin
+  #   Sevgi::Geometry::Point.angle(origin, [0, 10]) #=> 90.0
+  #   origin.translate(0, 10).below?(origin)        #=> true
+  # @see Sevgi::Geometry::Element::Lined
+  # @see Sevgi::Geometry::Operation
+  # @see https://sevgi.roktas.dev/geometry/ Geometry guide
   module Geometry
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-geometry
 version: !ruby/object:Gem::Version
-  version: 0.95.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,15 +15,15 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
-description: Enhances the Sevgi toolkit with geometry objects and methods.
+        version: 1.0.0
+description: Models the points, lines, shapes, and transforms used by the DSL.
 email: roktas@gmail.com
 executables: []
 extensions: []
@@ -34,6 +34,11 @@ files:
 - README.md
 - lib/sevgi/geometry.rb
 - lib/sevgi/geometry/element.rb
+- lib/sevgi/geometry/elements/arc.rb
+- lib/sevgi/geometry/elements/circle.rb
+- lib/sevgi/geometry/elements/ellipse.rb
+- lib/sevgi/geometry/elements/ellipse/affine.rb
+- lib/sevgi/geometry/elements/ellipse/length.rb
 - lib/sevgi/geometry/elements/line.rb
 - lib/sevgi/geometry/elements/parallelogram.rb
 - lib/sevgi/geometry/elements/polygon.rb
@@ -47,8 +52,10 @@ files:
 - lib/sevgi/geometry/internal.rb
 - lib/sevgi/geometry/operation.rb
 - lib/sevgi/geometry/operation/align.rb
+- lib/sevgi/geometry/operation/box.rb
 - lib/sevgi/geometry/operation/sweep.rb
 - lib/sevgi/geometry/point.rb
+- lib/sevgi/geometry/predicate.rb
 - lib/sevgi/geometry/segment.rb
 - lib/sevgi/geometry/version.rb
 homepage: https://sevgi.roktas.dev
@@ -73,7 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Tiny library for geometric computations.
+summary: Geometry values and operations for Sevgi drawings.
 test_files: []