math2d 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f3a494b2da989404d96ad8034d4b68f1ee7fa8280ce6f10e673e193fba05dc3b
+  data.tar.gz: 8f137444c95142d170c666456419ed07a601dd01f5593492ab0131909d3d3195
+SHA512:
+  metadata.gz: d2a54a7a4cdfb1a84553a5fe8ec22c4cfb1680273ce69d98c5979d0eec65cae88bb4072fa69aebf0b44a9d1f6d67c5a291d3207d44ff6e1c926b685007db8a98
+  data.tar.gz: b0a32b1a0b168ff16e6c8e0aec72e828df677035e031f4870fb2c62994f8b9dfa37d86be0d8738bf6816d6645ab9f6e8a3296600468b61ad4ed852f3abb9e598

data/lib/math2d/utils2d.rb

@@ -0,0 +1,158 @@
+# Namespace for the Math2D library
+module Math2D
+  # A collection of useful Mathematical tools in 2D space
+  #
+  # @author Ualace Henrique <ualacehenrique@hotmail.com>
+  # @note Most if not all methods descriptions here present come from the p5.js website.
+  # @see https://p5js.org/
+  module Utils2D
+    # Half the mathematical constant PI.
+    HALF_PI    = Math::PI / 2
+    # A quarter of the mathematical constant PI.
+    QUARTER_PI = Math::PI / 4
+    # Twice the mathematical constant PI.
+    TWO_PI     = Math::PI * 2
+
+    # Returns +angle+ radians in degrees.
+    #
+    # @param [Numeric] angle
+    # @return [Float]
+    def self.to_deg(angle)
+      (180 * angle) / Math::PI
+    end
+
+    # Returns +angle+ degrees in radians.
+    #
+    # @param [Numeric] angle
+    # @return [Float]
+    def self.to_rad(angle)
+      (Math::PI * angle) / 180
+    end
+
+    # Returns the distance between two cartesian points.
+    #
+    # @param [Numeric] x1
+    # @param [Numeric] y1
+    # @param [Numeric] x2
+    # @param [Numeric] y2
+    # @return [Float]
+    def self.distance(x1, y1, x2, y2)
+      Math.sqrt((x2 - x1)**2 + (y2 - y1)**2)
+    end
+
+    # Calculates a number between two numbers at a specific increment.
+    # The amt parameter is the amount to interpolate between the two
+    # values where 0.0 equal to the first point, 0.1 is very near the
+    # first point, 0.5 is half-way in between, and 1.0 is equal to the
+    # second point.
+    #
+    # @param [Numeric] a
+    # @param [Numeric] b
+    # @return [Float]
+    def self.lerp(a, b, amt)
+      (b - a) * (3.0 - amt * 2.0) * amt * amt + a
+    end
+
+    # Re-maps a number from one range (+a1+..+a2+) to another (+b1+..+b2+).
+    #
+    # @param [Numeric] value
+    # @param [Numeric] a1
+    # @param [Numeric] a2
+    # @param [Numeric] b1
+    # @param [Numeric] b2
+    # @return [Float]
+    def self.map(value, a1, a2, b1, b2)
+      raise ArgumentError, 'Division by 0 - a1 cannot be equal to a2' if a2 == a1
+
+      slope = 1.0 * (b2 - b1) / (a2 - a1)
+      b1 + slope * (value - a1)
+    end
+
+    # Normalizes a number from another range (+a+..+b+) into a value between 0 and 1.
+    #
+    # @param [Numeric] value
+    # @param [Numeric] a
+    # @param [Numeric] b
+    # @return [Float]
+    def self.normalize(value, a, b)
+      map(value, a, b, 0.0, 1.0)
+    end
+
+    # Constrains a value +x+ between a minimum value +a+ and maximum value +b+.
+    #
+    # @param [Numeric] x
+    # @param [Numeric] a
+    # @param [Numeric] b
+    # @return [Numeric]
+    def self.constrain(x, a, b)
+      [[x, a].max, b].min
+    end
+
+    class << self
+      alias clamp constrain
+    end
+
+    # Returns the Perlin noise value at specified coordinates.
+    # Perlin noise is a random sequence generator producing a more naturally
+    # ordered, harmonic succession of numbers compared to the standard rand() method.
+    # The main difference to the rand() method is that Perlin noise is defined in an
+    # infinite n-dimensional space where each pair of coordinates corresponds to a fixed
+    # semi-random value. Utils2D can compute 1D and 2D noise, depending on the number of
+    # coordinates given. The resulting value will always be between 0.0 and 1.0.
+    # @see https://en.wikipedia.org/wiki/Perlin_noise
+    #
+    # @param [Numeric] x
+    # @param [Numeric] y
+    # @return [Float]
+    def self.noise(x, y = 0)
+      x0 = x.to_i
+      x1 = x0 + 1
+      y0 = y.to_i
+      y1 = y0 + 1
+
+      sx = x - x0.to_f
+      sy = y - y0.to_f
+
+      n0 = dot_grid_gradient(x0, y0, x, y)
+      n1 = dot_grid_gradient(x1, y0, x, y)
+      ix0 = lerp(n0, n1, sx)
+
+      n0 = dot_grid_gradient(x0, y1, x, y)
+      n1 = dot_grid_gradient(x1, y1, x, y)
+      ix1 = lerp(n0, n1, sx)
+      lerp(ix0, ix1, sy)
+    end
+
+    # If no argument is passed, randomly generates a greyscale RGB array.
+    # Otherwise, returns a greyscale array with that argument normalized.
+    #
+    # @param [Numeric] val
+    # @return [Array<Float>]
+    def self.grayscale(val = nil)
+      c = if val
+            normalize(val, 0, 255).abs
+          else
+            rand
+          end
+      [c, c, c, 1.0]
+    end
+
+    private
+
+    # @private
+    # @see https://en.wikipedia.org/wiki/Perlin_noise
+    def self.random_gradient(ix, iy)
+      random = 2920.0 * Math.sin(ix * 21_942.0 + iy * 171_324.0 + 8912.0) * Math.cos(ix * 23_157.0 * iy * 217_832.0 + 9758.0)
+      [Math.cos(random), Math.sin(random)]
+    end
+
+    # @private
+    # @see https://en.wikipedia.org/wiki/Perlin_noise
+    def self.dot_grid_gradient(ix, iy, x, y)
+      gradient = random_gradient(ix, iy)
+      dx = x - ix.to_f
+      dy = y - iy.to_f
+      (dx * gradient[0]) + (dy * gradient[1])
+    end
+  end
+end

data/lib/math2d/vector2d.rb

@@ -0,0 +1,340 @@
+# Namespace for the Math2D gem
+module Math2D
+  # Vector2D
+  #
+  # - An implementation of various 2-dimensional vector methods.
+  #
+  # @author Ualace Henrique <ualacehenrique@hotmail.com>
+  # @note MOST methods return a NEW Vector2D instead of changing
+  #       self and returning it, so be careful.
+  # @attr [Numeric] x The x coordinate of the Vector
+  # @attr [Numeric] y The y coordinate of the Vector
+  class Vector2D
+    attr_accessor :x, :y
+
+    # Creates a new vector (x, y).
+    #
+    # @param [Numeric] x
+    # @param [Numeric] y
+    # @return [Vector2D]
+    def initialize(x = 0, y = 0)
+      @x = x
+      @y = y
+    end
+
+    # Sets the +x+ and +y+ components of the vector.
+    # Each argument is optional, so you can change a single component
+    # and keep the other one's current value.
+    #
+    # @param [Numeric] x
+    # @param [Numeric] y
+    # @return [Vector2D] self
+    def set(x = self.x, y = self.y)
+      @x = x
+      @y = y
+      self
+    end
+
+    # Shorthand for writing Vector2D.new(0, 0).
+    #
+    # @return [Vector2D]
+    def self.zero
+      Vector2D.new(0, 0)
+    end
+
+    # Shorthand for writing Vector2D.new(1, 1).
+    #
+    # @return [Vector2D]
+    def self.one
+      Vector2D.new(1, 1)
+    end
+
+    # Shorthand for writing Vector2D.new(0, -1).
+    # NOTE: the y-axis is inverted as per Ruby2D's y-axis orientation
+    #
+    # @return [Vector2D]
+    def self.up
+      Vector2D.new(0, -1)
+    end
+
+    # Shorthand for writing Vector2D.new(0, 1).
+    #
+    # @return [Vector2D]
+    def self.down
+      Vector2D.new(0, 1)
+    end
+
+    # Shorthand for writing Vector2D.new(-1, 0).
+    #
+    # @return [Vector2D]
+    def self.left
+      Vector2D.new(-1, 0)
+    end
+
+    # Shorthand for writing Vector2D.new(1, 0).
+    #
+    # @return [Vector2D]
+    def self.right
+      Vector2D.new(1, 0)
+    end
+
+    # Negates both x and y values of +self+ and returns a new Vector2D.
+    #
+    # @return [Vector2D]
+    def -@
+      Vector2D.new(-@x, -@y)
+    end
+
+    alias negate -@
+
+    # Adds +self+ to another vector or to a scalar.
+    #
+    # @param [Numeric, Vector2D] other
+    # @return [Vector2D]
+    def +(other)
+      return Vector2D.new(@x + other.x, @y + other.y) if other.instance_of?(Vector2D)
+
+      Vector2D.new(@x + other, @y + other)
+    end
+
+    # Subtracts +self+ to another vector or to a scalar.
+    #
+    # @param [Numeric, Vector2D] other
+    # @return [Vector2D]
+    def -(other)
+      return Vector2D.new(@x - other.x, @y - other.y) if other.instance_of?(Vector2D)
+
+      Vector2D.new(@x - other, @y - other)
+    end
+
+    # Multiplies +self+ by another vector or by a scalar.
+    #
+    # @param [Numeric, Vector2D] other
+    # @return [Vector2D]
+    def *(other)
+      return Vector2D.new(@x * other.x, @y * other.y) if other.instance_of?(Vector2D)
+
+      Vector2D.new(@x * other, @y * other)
+    end
+
+    # Divides +self+ by another vector or by a scalar.
+    #
+    # @param [Numeric, Vector2D] other
+    # @return [Vector2D]
+    def /(other)
+      return Vector2D.new(@x / other.x, @y / other.y) if other.instance_of?(Vector2D)
+
+      Vector2D.new(@x / other, @y / other)
+    end
+
+    # Calculates the dot product between +self+ and +other+, where:
+    # A.B (A dot B) = (Ax * Bx) + (Ay * By)
+    #
+    # @param [Vector2D] other
+    # @return [Numeric]
+    def dot(other)
+      (@x * other.x) + (@y * other.y)
+    end
+
+    # Calculates the cross product between +self+ and +other+, where:
+    # AxB (A cross B) = (Ax * By) - (Bx * Ay)
+    # HOWEVER, the cross product is NOT defined in a 2D space, so the operation
+    # simply returns the magnitude of the resulting cross-product 3D vector.
+    #
+    # @param [Vector2D] other
+    # @return [Numeric]
+    def cross(other)
+      (@x * other.y) - (other.x * @y)
+    end
+
+    # Returns the magnitude squared of +self+.
+    #
+    # @return [Numeric]
+    def squared
+      (@x**2) + (@y**2)
+    end
+
+    # Returns the magnitude of +self+.
+    #
+    # @return [Float]
+    def magnitude
+      Math.sqrt(@x**2 + @y**2)
+    end
+
+    # Returns the Euclidean distance between +self+ and +other+.
+    #
+    # @param [Vector2D] other
+    # @return [Float]
+    def distance(other)
+      Math.sqrt((other.x - @x)**2 + (other.y - @y)**2)
+    end
+
+    # Returns the ratio (x / y) of +self+.
+    #
+    # @return [Float]
+    def ratio
+      x.to_f / y
+    end
+
+    # Limit the magnitude of +self+ to +max+ and returns a new vector.
+    #
+    # @param [Numeric] max
+    # @return [Vector2D]
+    def limit(max)
+      msq = squared
+      vec = self
+      if msq > (max**2)
+        vec /= Math.sqrt(msq)
+        vec *= max
+      end
+      vec
+    end
+
+    # Constrains the magnitude of +self+ between a minimum value +a+ and maximum value +b+.
+    #
+    # @note I haven't experienced this with other methods (yet), so I'm only going to document this
+    #       here: you may end up with a broken magnitude (1.99999999 instead of 2, for example),
+    #       so always remember to check and round according to your need.
+    # @param [Numeric] a
+    # @param [Numeric] b
+    # @return [Vector2D]
+    def constrain(a, b)
+      mag = magnitude
+      v = Vector2D.one
+      if mag > b
+        v.set_magnitude(b)
+      elsif mag < a
+        v.set_magnitude(a)
+      end
+    end
+
+    alias clamp constrain
+
+    # Sets the magnitude of +self+ to +new_mag+.
+    #
+    # @param [Numeric] new_mag
+    # @return [Vector2D]
+    def set_magnitude(new_mag)
+      mag = magnitude
+      mag = mag.zero? ? Float::INFINITY : mag
+      Vector2D.new((@x * new_mag) / mag, (@y * new_mag) / mag)
+    end
+
+    # Normalizes +self+ (set the magnitude to 1).
+    # +unit+ is an alias for this method.
+    #
+    # @return [Vector2D]
+    def normalize
+      set_magnitude(1)
+    end
+
+    alias unit normalize
+
+    # Returns true if the magnitude of +self+ is equal to 1, false otherwise.
+    # +unit?+ is an alias for this method.
+    #
+    # @return [Boolean]
+    def normalized?
+      magnitude == 1
+    end
+
+    alias unit? normalized?
+
+    # Returns the x-heading angle of +self+ in radians.
+    # The x-heading angle is the angle formed between +self+ and the x-axis.
+    #
+    # @return [Float]
+    def heading
+      Math.atan2(@y.to_f, @x)
+    end
+
+    # Returns the y-heading angle of +self+ in radians.
+    # The y-heading angle is the angle formed between +self+ and the y-axis.
+    #
+    # @return [Float]
+    def y_heading
+      Utils2D::HALF_PI - heading
+    end
+
+    # Returns a new Vector2D from a given angle +theta+ with length +len+.
+    #
+    # @param [Numeric] theta
+    # @param [Numeric] len
+    # @return [Vector2D]
+    def self.from_angle(theta, len = 1)
+      Vector2D.new(len * Math.cos(theta), len * Math.sin(theta))
+    end
+
+    # Returns the angle between +self+ and +other+ in radians.
+    #
+    # @param [Vector2D] other
+    # @return [Float]
+    def angle_between(other)
+      Math.acos((@x * other.x + @y * other.y) / (magnitude * other.magnitude))
+    end
+
+    # Rotates +self+ +angle+ radians and returns it as a new Vector2D.
+    #
+    # @param [Numeric] angle
+    # @return [Vector2D]
+    def rotate(angle)
+      Vector2D.new(@x * Math.cos(angle) - @y * Math.sin(angle),
+                   @x * Math.sin(angle) + @y * Math.cos(angle))
+    end
+
+    # Linear interpolate +self+ and +other+ with an amount +amt+.
+    #
+    # @param [Numeric, Vector2D] other
+    # @param [Numeric] amt
+    # @return [Vector2D]
+    def lerp(other, amt)
+      self + (other - self) * amt
+    end
+
+    # Reflects +self+ and returns it as a new Vector2D.
+    # +other+ is the normal of the plane where +self+ is reflected.
+    #
+    # @param [Vector2D] other
+    # @return [Vector2D]
+    def reflect(other)
+      other = other.normalize
+      dot_prod = other.dot(self)
+      x = @x - dot_prod * other.x * 2
+      y = @y - dot_prod * other.y * 2
+      Vector2D.new(x, y)
+    end
+
+    # Returns a new Vector2D with random components but magnitude equal to 1.
+    #
+    # @return [Vector2D]
+    def self.random
+      theta = rand(-Utils2D::TWO_PI..Utils2D::TWO_PI)
+      Vector2D.new(Math.cos(theta), Math.sin(theta))
+    end
+
+    # Converts +self+ to an array.
+    #
+    # @return [Array<Numeric>]
+    def to_a
+      [@x, @y]
+    end
+
+    # Converts +self+ to a string.
+    #
+    # @return [String]
+    def to_s
+      to_a.to_s
+    end
+
+    # Returns a new Vector2D from an array +arr+.
+    # If the array is bigger than 2 elements, only the first 2 will be considered.
+    #
+    # @param [Array<Numeric>] arr
+    # @return [Vector2D]
+    def self.to_vector(arr)
+      raise ArgumentError, '`arr` must be an Array' if arr.class != Array
+
+      Vector2D.new(arr[0], arr[1])
+    end
+  end
+end

data/lib/math2d.rb

@@ -0,0 +1,9 @@
+require_relative 'math2d/vector2d'
+require_relative 'math2d/utils2d'
+
+# Namespace for the Math2D library
+#
+# @author Ualace Henrique <ualacehenrique@hotmail.com>
+module Math2D; end
+
+include Math2D

metadata

@@ -0,0 +1,45 @@
+--- !ruby/object:Gem::Specification
+name: math2d
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- Ualace Henrique
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-07-25 00:00:00.000000000 Z
+dependencies: []
+description: A collection of useful Mathematical and Vector tools in 2D space
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/math2d.rb
+- lib/math2d/utils2d.rb
+- lib/math2d/vector2d.rb
+homepage: https://rubygems.org/gems/math2d
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.16
+signing_key:
+specification_version: 4
+summary: Math2D
+test_files: []