sevgi-geometry 0.73.2 → 0.93.1

data/lib/sevgi/geometry/point.rb

@@ -2,80 +2,177 @@
 
 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
 
+      # Creates a point.
+      # @param x [Numeric] x coordinate
+      # @param y [Numeric] y coordinate
+      # @return [void]
       def initialize(x:, y:) = super(x: x.to_f, y: y.to_f)
 
+      # 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

data/lib/sevgi/geometry/segment.rb

@@ -2,59 +2,133 @@
 
 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]
+      # 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]
       def initialize(length:, angle:) = super(length: length.to_f, angle: angle.to_f)
 
+      # 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.93.1"
   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.93.1
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.93.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.93.1
 description: Enhances the Sevgi toolkit with geometry objects and methods.
 email: roktas@gmail.com
 executables: []
@@ -36,11 +36,11 @@ files:
 - 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

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