sevgi-geometry 0.73.2 → 0.94.0

data/lib/sevgi/geometry/segment.rb

@@ -2,59 +2,134 @@
 
 module Sevgi
   module Geometry
+    # Immutable polar segment 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.
     Segment = Data.define(:length, :angle) do
       include Comparable
 
+      # @!attribute [r] length
+      #   @return [Float] segment length
+      # @!attribute [r] angle
+      #   @return [Float] clockwise angle in degrees
+
+      # Creates a segment from start and end points.
+      # @param starting [Sevgi::Geometry::Point, Array<Numeric>] start point
+      # @param ending [Sevgi::Geometry::Point, Array<Numeric>] end point
+      # @return [Sevgi::Geometry::Segment]
+      # @raise [Sevgi::Geometry::Error] when either point cannot be coerced
       def self.call(starting, ending)
         starting, ending = Tuples[Point, starting, ending]
         self[Point.length(starting, ending), Point.angle(starting, ending)]
       end
 
+      # Compares two segments with optional numeric precision.
+      # @param this [Sevgi::Geometry::Segment, Array<Numeric>] first segment
+      # @param that [Sevgi::Geometry::Segment, Array<Numeric>] second segment
+      # @param precision [Integer, nil] decimal precision, or nil for the current function default
+      # @return [Boolean]
+      # @raise [Sevgi::Geometry::Error] when either segment cannot be coerced
       def self.eq?(this, that, precision: nil)
         this, that = Tuples[self, this, that]
         F.eq?(this.length, that.length, precision:) && F.eq?(this.angle, that.angle, precision:)
       end
 
-      def self.horizontal!(length) = self[length, 180.0]
-      def self.horizontal(length) = self[length, 0.0]
-      def self.vertical!(length) = self[length, -90.0]
-      def self.vertical(length) = self[length, 90.0]
-
-      def initialize(length:, angle:) = super(length: length.to_f, angle: angle.to_f)
+      # Returns a downward segment.
+      # @param length [Numeric] segment length
+      # @return [Sevgi::Geometry::Segment]
+      def self.downward(length) = self[length, 90.0]
+
+      # Returns a leftward segment.
+      # @param length [Numeric] segment length
+      # @return [Sevgi::Geometry::Segment]
+      def self.leftward(length) = self[length, 180.0]
+
+      # Returns a rightward segment.
+      # @param length [Numeric] segment length
+      # @return [Sevgi::Geometry::Segment]
+      def self.rightward(length) = self[length, 0.0]
+
+      # Returns an upward segment.
+      # @param length [Numeric] segment length
+      # @return [Sevgi::Geometry::Segment]
+      def self.upward(length) = self[length, -90.0]
+
+      class << self
+        # @return [Sevgi::Geometry::Segment]
+        alias_method :horizontal, :rightward
+        # @return [Sevgi::Geometry::Segment]
+        alias_method :vertical, :downward
+      end
 
+      # Creates a segment.
+      # @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])
+
+      # 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) = (other = Tuple[Segment, other]).nan? || nan? ? nil : length <=> other.length
 
+      # Returns a segment rounded to precision.
+      # @param precision [Integer, nil] decimal precision, or nil for the current function default
+      # @return [Sevgi::Geometry::Segment]
       def approx(precision = nil) = with(length: F.approx(length, precision), angle: F.approx(angle, precision))
 
-      def com = angle - 90.0
-
+      # Returns the endpoint reached from a starting point.
+      # @param starting [Sevgi::Geometry::Point, Array<Numeric>] start point
+      # @return [Sevgi::Geometry::Point]
+      # @raise [Sevgi::Geometry::Error] when starting cannot be coerced
       def ending(starting) = Tuple[Point, starting].translate(x, y)
 
+      # Compares this segment with optional numeric precision.
+      # @param other [Sevgi::Geometry::Segment, Array<Numeric>] segment 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 segment 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 component is infinite.
+      # @return [Boolean]
       def infinite? = deconstruct.any?(&:infinite?)
 
+      # Converts the segment into a line at a point.
+      # @param point [Sevgi::Geometry::Point, Array<Numeric>] line start point
+      # @return [Sevgi::Geometry::Line]
+      # @raise [Sevgi::Geometry::Error] when point cannot be coerced
       def line(point = Origin) = Line[length, angle, position: Tuple[Point, point]]
 
-      def lx = x.abs
-
-      def ly = y.abs
-
+      # Reports whether any component is NaN.
+      # @return [Boolean]
       def nan? = deconstruct.any?(&:nan?)
 
+      # Returns the opposite segment.
+      # @return [Sevgi::Geometry::Segment]
       def reverse = with(angle: angle + 180.0)
 
-      def sup = angle - 180.0
-
+      # Returns the x component of the segment.
+      # @return [Float]
       def x = length * F.cos(angle)
 
+      # Returns the y component of the segment.
+      # @return [Float]
       def y = length * F.sin(angle)
     end
 
-    LengthAngle = Data.define(:length, :angle)
+    # Lightweight polar value used where a plain length/angle tuple is enough.
+    Polar = Data.define(:length, :angle)
   end
 end

data/lib/sevgi/geometry/version.rb

@@ -2,6 +2,7 @@
 
 module Sevgi
   module Geometry
-    VERSION = "0.73.2"
+    # Component version.
+    VERSION = "0.94.0"
   end
 end

data/lib/sevgi/geometry.rb

@@ -12,3 +12,12 @@ 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.
+  #
+  # Coordinates follow SVG screen conventions: +x points right, +y points down,
+  # and positive angles turn clockwise.
+  module Geometry
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-geometry
 version: !ruby/object:Gem::Version
-  version: 0.73.2
+  version: 0.94.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,32 +15,31 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.94.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.94.0
 description: Enhances the Sevgi toolkit with geometry objects and methods.
 email: roktas@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
 - README.md
 - lib/sevgi/geometry.rb
 - lib/sevgi/geometry/element.rb
-- lib/sevgi/geometry/elements/circle.rb
-- lib/sevgi/geometry/elements/curve.rb
-- lib/sevgi/geometry/elements/ellipse.rb
 - lib/sevgi/geometry/elements/line.rb
-- lib/sevgi/geometry/elements/parm.rb
+- lib/sevgi/geometry/elements/parallelogram.rb
 - lib/sevgi/geometry/elements/polygon.rb
 - lib/sevgi/geometry/elements/polyline.rb
 - lib/sevgi/geometry/elements/rect.rb
-- lib/sevgi/geometry/elements/tri.rb
+- lib/sevgi/geometry/elements/triangle.rb
 - lib/sevgi/geometry/equation.rb
 - lib/sevgi/geometry/equation/linear.rb
 - lib/sevgi/geometry/equation/quadratic.rb
@@ -67,7 +66,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.4.0.pre.preview1
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

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

@@ -1 +0,0 @@
-

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

@@ -1 +0,0 @@
-

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

@@ -1 +0,0 @@
-

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

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-# Parallelogram
-
-module Sevgi
-  module Geometry
-    class Parm < Element.lined(4)
-      def self.[](horizontal, vertical, position: Origin)
-        horizontal, vertical = Tuples[Segment, horizontal, vertical]
-
-        new_by_segments(horizontal, vertical.reverse, horizontal.reverse, vertical, position:)
-      end
-
-      def self.new_by_height(horizontal:, tallness:, position: Origin)
-        horizontal = Tuple[Segment, horizontal]
-        tallness = Tuple[LengthAngle, tallness]
-
-        height = tallness.length - horizontal.ly
-        angle = tallness.angle
-        length = height / F.sin(angle)
-
-        self[horizontal, Segment[length, angle], position:]
-      end
-
-      def self.new_by_width(vertical:, wideness:, position: Origin)
-        vertical = Tuple[Segment, vertical]
-        wideness = Tuple[LengthAngle, wideness]
-
-        width = wideness.length - vertical.lx
-        angle = wideness.angle
-        length = width / F.cos(angle)
-
-        self[Segment[length, angle], vertical, position:]
-      end
-    end
-  end
-end

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

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Sevgi
-  module Geometry
-    class Tri < Element.lined(3)
-      def self.[](segment_a, segment_b, position: Origin)
-        a, b = Tuples[Segment, segment_a, segment_b]
-
-        length = ::Math.sqrt((a.length ** 2) + (b.length ** 2) - (2 * a.length * b.length * F.cos(b.sup - a.angle)))
-        angle = b.sup + F.asin(a.length * F.sin(b.sup - a.angle) / length)
-
-        c = Segment[length, angle]
-
-        new_by_segments(a, b, c, position:)
-      end
-    end
-  end
-end