math2d 1.2.1 → 1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fa9e7785755d0911beda7ece84a14f4b0234d9103ae593b556237be3403973e
-  data.tar.gz: ba748b29f8499d5ef2504942b4ee7c7dc3c9bad9d6fb5393f9aa78fd6d303cab
+  metadata.gz: 687573d7fe97c2627cea246b39ff246058cd1dce63c4163c6e4c9955db5bf00c
+  data.tar.gz: 9475dc4a1a0b96f5c6133a171159151469d39d0a8d495c759286530f5880596e
 SHA512:
-  metadata.gz: c494f9101b180ec9d2072630d48bbb9e0b99b404dec093ccaf35b4856cd75a8a11d4eed8478449a51f5bc3a37a239d37ab6899c35c558b24ff439490a64b88ff
-  data.tar.gz: 4f79cd577b4c2686e07fe8b36b30cf28f8b1e4aac13e48e51df3d9e0a64b80454ca10076dbe06734d36b511cacb044a0101a5e614cebb766bb5a7dce880df84d
+  metadata.gz: e382704a1edebfb80e669128eaf2838468eb2429435513f2c8af7cf582e5483511c08cc62334f0d24e38eb937610837d4f741f9193145bc5e029869876b4bd6c
+  data.tar.gz: 625524b71e0d8c4b609cf846b89814bd3364f968b8f7276a3f31823720b6d41f2bc1116177d608cafa1696587736207cd020345236ce995e1e5992676efa71ad

data/lib/math2d/utils2d.rb

@@ -13,12 +13,19 @@ module Math2D
     # Twice the mathematical constant PI, also called TAU.
     TWO_PI = TAU = Math::PI * 2
 
+    # Multiplication constant to convert a value in degrees to radians.
+    # @note Can be used as a substitute to +Utils2D.to_rad+.
+    DEG2RAD      = Math::PI / 180
+    # Multiplication constant to convert a value in radians to degrees.
+    # @note Can be used as a substitute to +Utils2D.to_deg+.
+    RAD2DEG      = 180 / Math::PI
+
     # Returns +angle+ radians in degrees.
     #
     # @param [Numeric] angle
     # @return [Float]
     def self.to_deg(angle)
-      (180 * angle) / Math::PI
+      angle * RAD2DEG
     end
 
     # Returns +angle+ degrees in radians.
@@ -26,7 +33,7 @@ module Math2D
     # @param [Numeric] angle
     # @return [Float]
     def self.to_rad(angle)
-      (Math::PI * angle) / 180
+      angle * DEG2RAD
     end
 
     # Returns the distance between two cartesian points.
@@ -48,11 +55,23 @@ module Math2D
     #
     # @param [Numeric] a
     # @param [Numeric] b
+    # @param [Numeric] amt
     # @return [Float]
     def self.lerp(a, b, amt)
       (b - a) * (3.0 - amt * 2.0) * amt * amt + a
     end
 
+    # Being the inverse of +#lerp+, it calculates the interpolation parameter t
+    #  of the Lerp method given a range [+a+, +b+] and a interpolant value of +value+.
+    #
+    # @param [Numeric] a
+    # @param [Numeric] b
+    # @param [Numeric] value
+    # @return [Float]
+    def self.inverse_lerp(a, b, value)
+      (value - a) / (b - a).to_f
+    end
+
     # Re-maps a number from one range (+a1+..+a2+) to another (+b1+..+b2+).
     #
     # @param [Numeric] value
@@ -123,8 +142,8 @@ module Math2D
       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.
+    # If no argument is passed, randomly generates a grayscale RGB array.
+    # Otherwise, returns a grayscale array with that argument normalized.
     #
     # @param [Numeric] val
     # @return [Array<Float>]
@@ -137,6 +156,10 @@ module Math2D
       [c, c, c, 1.0]
     end
 
+    class << self
+      alias greyscale grayscale
+    end
+
     private
 
     # @private

data/lib/math2d/vector2d.rb

@@ -5,8 +5,10 @@ module Math2D
   # - 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.
+  # @note ALL ! (bang) methods that return a vector (e.g. #normalize!, #add!) change the vector in place
+  #       and return _self_.
+  # @note MOST (but not all) regular methods that return a vector create NEW _Vector2D_. Some however change the
+  #       vector in place and return _self_, so be careful.
   # @attr [Numeric] x The x coordinate of the Vector
   # @attr [Numeric] y The y coordinate of the Vector
   class Vector2D
@@ -18,8 +20,27 @@ module Math2D
     # @param [Numeric] y
     # @return [Vector2D]
     def initialize(x = 0, y = 0)
-      @x = x
-      @y = y
+      @x = x.to_f
+      @y = y.to_f
+    end
+
+    # Creates a copy of the +other+ vector.
+    #
+    # @param [Vector2D] other Vector to copy
+    # @return [Vector2D]
+    def initialize_copy(other)
+      @x = other.x
+      @y = other.y
+    end
+
+    # Replace contents of this vector with contents of +other+ *in place*.
+    #
+    # @param [Vector2D] other
+    # @return [Vector2D] modified vector
+    def replace!(other)
+      @x = other.x
+      @y = other.y
+      self
     end
 
     # Sets the +x+ and +y+ components of the vector.
@@ -30,8 +51,8 @@ module Math2D
     # @param [Numeric] y
     # @return [Vector2D] self
     def set(x = self.x, y = self.y)
-      @x = x
-      @y = y
+      @x = x.to_f
+      @y = y.to_f
       self
     end
 
@@ -80,51 +101,64 @@ module Math2D
 
     # Negates both x and y values of +self+ and returns a new Vector2D.
     #
-    # @return [Vector2D]
+    # @return [Vector2D] new vector
     def -@
       Vector2D.new(-@x, -@y)
     end
 
     alias negate -@
+    alias reverse -@
 
-    # 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)
+    # Negate this vector, modifying it in place
+    #
+    # @return [Vector2D] modified self
+    def reverse!
+      @x = -@x
+      @y = -@y
+      self
+    end
+
+    alias negate! reverse!
 
-      Vector2D.new(@x + other, @y + other)
+    # Adds +self+ to another vector, scalar, or array of two scalars
+    #
+    # @param [Numeric, Vector2D, Array] other
+    # @return [Vector2D] new vector
+    def +(other)
+      clone.plus!(other)
     end
 
-    # Subtracts +self+ to another vector or to a scalar.
+    # Subtracts +self+ from another vector, scalar, or array of two scalars
     #
-    # @param [Numeric, Vector2D] other
-    # @return [Vector2D]
+    # @param [Numeric, Vector2D, Array] other
+    # @return [Vector2D] new vector
     def -(other)
-      return Vector2D.new(@x - other.x, @y - other.y) if other.instance_of?(Vector2D)
-
-      Vector2D.new(@x - other, @y - other)
+      clone.minus!(other)
     end
 
-    # Multiplies +self+ by another vector or by a scalar.
+    # Multiplies +self+ by another vector, scalar, or array of two scalars
     #
-    # @param [Numeric, Vector2D] other
-    # @return [Vector2D]
+    # @param [Numeric, Vector2D, Array] other
+    # @return [Vector2D] new vector
     def *(other)
-      return Vector2D.new(@x * other.x, @y * other.y) if other.instance_of?(Vector2D)
-
-      Vector2D.new(@x * other, @y * other)
+      clone.times!(other)
     end
 
-    # Divides +self+ by another vector or by a scalar.
+    # Divides +self+ by another vector, scalar, or array of two scalars
     #
-    # @param [Numeric, Vector2D] other
-    # @return [Vector2D]
+    # @param [Numeric, Vector2D, Array] other
+    # @return [Vector2D] new vector
     def /(other)
-      return Vector2D.new(@x / other.x, @y / other.y) if other.instance_of?(Vector2D)
+      clone.divide_by!(other)
+    end
 
-      Vector2D.new(@x / other, @y / other)
+    # Compares +self+ and +other+ according to their components.
+    #
+    # @param [Vector2D] other
+    # @return [Boolean]
+    def ==(other)
+      (@x == other.x) && (@y == other.y)
     end
 
     # Calculates the dot product between +self+ and +other+, where:
@@ -136,10 +170,12 @@ module Math2D
       (@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.
+    # Calculates the "cross product" (see note) between +self+ and +other+, where:
+    # A^B (A wedge B) = (Ax * By) - (Bx * Ay)
+    #
+    # @note Strictly speaking, the cross product is not defined in a 2-dimensional space,
+    # instead what is being calculated here is called a `wedge product`, which is defined
+    # in any space of dimension greater than 1.
     #
     # @param [Vector2D] other
     # @return [Numeric]
@@ -147,6 +183,8 @@ module Math2D
       (@x * other.y) - (other.x * @y)
     end
 
+    alias wedge cross
+
     # Returns the magnitude squared of +self+.
     #
     # @return [Numeric]
@@ -154,6 +192,8 @@ module Math2D
       (@x**2) + (@y**2)
     end
 
+    alias magnitude2 squared
+
     # Returns the magnitude of +self+.
     #
     # @return [Float]
@@ -161,6 +201,18 @@ module Math2D
       Math.sqrt(@x**2 + @y**2)
     end
 
+    alias length magnitude
+
+    # Returns the squared Euclidean distance between +self+ and +other+. When comparing
+    # distances, comparing the squared distance yields the same result without the
+    # overhead of a square-root operation.
+    #
+    # @param [Vector2D] other
+    # @return [Float]
+    def distance2(other)
+      (other.x - @x)**2 + (other.y - @y)**2
+    end
+
     # Returns the Euclidean distance between +self+ and +other+.
     #
     # @param [Vector2D] other
@@ -179,32 +231,32 @@ module Math2D
     # Limit the magnitude of +self+ to +max+ and returns a new vector.
     #
     # @param [Numeric] max
-    # @return [Vector2D]
+    # @return [Vector2D] new vector
     def limit(max)
       msq = squared
-      vec = self
-      if msq > (max**2)
-        vec /= Math.sqrt(msq)
-        vec *= max
-      end
-      vec
+      return self if msq <= (max**2)
+
+      self * (max / Math.sqrt(msq))
     end
 
-    # Constrains the magnitude of +self+ between a minimum value +a+ and maximum value +b+.
+    # Constrains the magnitude of +self+ between a minimum value +min+ and maximum value +max+, returns a new
+    # vector or itself.
     #
     # @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)
+    # @param [Numeric] min
+    # @param [Numeric] max
+    # @return [Vector2D] new vector, or self
+    def constrain(min, max)
+      min, max = max, min if min > max # swap
+      mag2 = magnitude2
+      if mag2 > max.abs2
+        Vector2D.one.set_magnitude(max)
+      elsif mag2 < min.abs2
+        Vector2D.one.set_magnitude(min)
+      else
+        self
       end
     end
 
@@ -213,22 +265,26 @@ module Math2D
     # Sets the magnitude of +self+ to +new_mag+.
     #
     # @param [Numeric] new_mag
-    # @return [Vector2D]
+    # @return [Vector2D] modified self
     def set_magnitude(new_mag)
       mag = magnitude
-      mag = mag.zero? ? Float::INFINITY : mag
-      Vector2D.new((@x * new_mag) / mag, (@y * new_mag) / mag)
+      mag = Float::INFINITY if mag.zero?
+      self * (new_mag / mag)
     end
 
+    alias magnitude! set_magnitude
+
     # Normalizes +self+ (set the magnitude to 1).
     # +unit+ is an alias for this method.
     #
-    # @return [Vector2D]
+    # @return [Vector2D] modified self
     def normalize
       set_magnitude(1)
     end
 
-    alias unit normalize
+    alias normalize! normalize
+    alias unit! normalize!
+    alias unit normalize!
 
     # Returns true if the magnitude of +self+ is equal to 1, false otherwise.
     # +unit?+ is an alias for this method.
@@ -273,36 +329,76 @@ module Math2D
       Math.acos((@x * other.x + @y * other.y) / (magnitude * other.magnitude))
     end
 
+    # Checks if +self+ is facing the opposite direction of +other+.
+    #
+    # @param [Vector2D] other
+    # @return [Boolean]
+    def opposite?(other)
+      dot(other).negative?
+    end
+
     # Clockwise rotates +self+ +angle+ radians and returns it as a new Vector2D.
     #
     # @param [Numeric] angle
-    # @return [Vector2D]
+    # @return [Vector2D] new vector
     def rotate(angle)
-      Vector2D.new(
-        @x * Math.cos(angle) - @y * Math.sin(angle),
-        @x * Math.sin(angle) + @y * Math.cos(angle)
-      )
+      clone.rotate!(angle)
+    end
+
+    # Clockwise rotates +self+ by +angle+ radians *in place*
+    #
+    # @param [Numeric] angle
+    # @return [Vector2D] modified self
+    def rotate!(angle)
+      sin_ang = Math.sin(angle)
+      cos_ang = Math.cos(angle)
+      @x = @x * cos_ang - @y * sin_ang
+      @y = @x * sin_ang + @y * cos_ang
     end
 
     # Clockwise rotates +self+ +angle+ radians around a +pivot+ point and returns it as a new Vector2D.
     #
     # @param [Vector2D] pivot
     # @param [Numeric] angle
-    # @return [Vector2D]
+    # @return [Vector2D] new vector
     def rotate_around(pivot, angle)
-      x_rotated = pivot.x + ((@x - pivot.x) * Math.cos(angle)) - ((@y - pivot.y) * Math.sin(angle))
-      y_rotated = pivot.y + ((@x - pivot.x) * Math.sin(angle)) + ((@y - pivot.y) * Math.cos(angle))
+      clone.rotate_around!(pivot, angle)
+    end
 
-      Vector2D.new(x_rotated, y_rotated)
+    # Clockwise rotates +self+ by +angle+ radians around a +pivot+ point *in place*
+    #
+    # @param [Vector2D] pivot
+    # @param [Numeric] angle
+    # @return [Vector2D] modified self
+    def rotate_around!(pivot, angle)
+      pivot_x = pivot.x
+      pivot_y = pivot.y
+      dx = (@x - pivot_x)
+      dy = (@y - pivot_y)
+      sin_ang = Math.sin(angle)
+      cos_ang = Math.cos(angle)
+      @x = pivot_x + (dx * cos_ang) - (dy * sin_ang)
+      @y = pivot_y + (dx * sin_ang) + (dy * cos_ang)
     end
 
     # Linear interpolate +self+ and +other+ with an amount +amt+.
     #
     # @param [Numeric, Vector2D] other
     # @param [Numeric] amt
-    # @return [Vector2D]
+    # @return [Vector2D] new vector
     def lerp(other, amt)
-      self + (other - self) * amt
+      Vector2D.new @x + (other.x - @x) * amt,
+                   @y + (other.y - @y) * amt
+      # self + (other - self) * amt
+    end
+
+    # Calculates the parameter t of the +#lerp+ method between +self+ and +other+ given an interpolant +value+.
+    #
+    # @param [Numeric, Vector2D] other
+    # @param [Vector2D] value
+    # @return [Vector2D]
+    def inverse_lerp(other, value)
+      (value - self) / (other - self)
     end
 
     # Reflects +self+ and returns it as a new Vector2D.
@@ -313,8 +409,27 @@ module Math2D
     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 - dot_prod * other.x * 2,
+                   @y - dot_prod * other.y * 2
+    end
+
+    # Refracts +self+ and returns it as a new Vector2D.
+    # +other+ is the normal of the plane where +self+ is refracted.
+    #
+    # @see https://www.khronos.org/registry/OpenGL/specs/gl/GLSLangSpec.1.20.pdf GLS Language Specification (page 66)
+    # @see https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/refract.xhtml
+    #
+    # @param [Vector2D] other
+    # @param [Numeric] refractive_index
+    # @return [Vector2D]
+    def refract(other, refractive_index)
+      dot_prod = other.dot(self)
+      k = 1.0 - refractive_index.abs2 * (1.0 - dot_prod.abs2)
+      return Vector2D.zero if k.negative?
+
+      other_refraction = (refractive_index * dot_prod * Math.sqrt(k))
+      x = refractive_index * @x - other_refraction * other.x
+      y = refractive_index * @y - other_refraction * other.y
       Vector2D.new(x, y)
     end
 
@@ -340,6 +455,26 @@ module Math2D
       to_a.to_s
     end
 
+    # Returns a *new vector* of the clockwise perpendicular to this vector.
+    #
+    # @return [Vector2D]
+    #
+    def vector_cross_product
+      Vector2D.new @y, -@x
+    end
+
+    alias perp vector_cross_product
+
+    # Replace this vector with it's clockwise perpendicular
+    #
+    # @return [Vector2D] modified self
+    def vector_cross_product!
+      @x, @y = @y, -@x
+      self
+    end
+
+    alias perp! vector_cross_product!
+
     # Returns a new Vector2D from an array +arr+.
     # If the array is bigger than 2 elements, only the first 2 will be considered.
     #
@@ -350,5 +485,103 @@ module Math2D
 
       Vector2D.new(arr[0], arr[1])
     end
+
+    # Multiplies +self+ by +delta+ in place.
+    #
+    # @param [Numeric, Vector2D, Array] delta
+    # @return [Vector2D] modified self
+    def times!(delta)
+      case delta
+      when Vector2D
+        @x *= delta.x
+        @y *= delta.y
+      when Array
+        @x *= delta[0]
+        @y *= delta[1]
+      else
+        @x *= delta
+        @y *= delta
+      end
+      self
+    end
+
+    # Subtracts +delta+ from +self+ in place.
+    #
+    # @param [Numeric, Vector2D, Array] delta
+    # @return [Vector2D] modified self
+    def minus!(delta)
+      case delta
+      when Vector2D
+        @x -= delta.x
+        @y -= delta.y
+      when Array
+        @x -= delta[0]
+        @y -= delta[1]
+      else
+        @x -= delta
+        @y -= delta
+      end
+      self
+    end
+
+    # Adds +delta+ to +self+ in place.
+    #
+    # @param [Numeric, Vector2D, Array] delta
+    # @return [Vector2D] modified self
+    def plus!(delta)
+      case delta
+      when Vector2D
+        @x += delta.x
+        @y += delta.y
+      when Array
+        @x += delta[0]
+        @y += delta[1]
+      else
+        @x += delta
+        @y += delta
+      end
+      self
+    end
+
+    # Divides +self+ by +delta+ in place.
+    #
+    # @param [Numeric, Vector2D, Array] delta
+    # @return [Vector2D] modified self
+    def divide_by!(delta)
+      case delta
+      when Vector2D
+        @x /= delta.x
+        @y /= delta.y
+      when Array
+        @x /= delta[0]
+        @y /= delta[1]
+      else
+        @x /= delta
+        @y /= delta
+      end
+      self
+    end
+
+    # Add +dx+ and +dy+ to the current vector's components, respectively
+    #
+    # @param [Numeric] dx
+    # @param [Numeric] dy
+    # @return [Vector2d] modified self
+    def add!(dx, dy)
+      @x += dx
+      @y += dy
+      self
+    end
+
+    # Subtract +dx+ and +dy+ _from_ the current vector's components, respectively
+    #
+    # @param [Numeric] dx
+    # @param [Numeric] dy
+    # @return [Vector2d] modified self
+    def subtract!(dx, dy)
+      @x -= dx
+      @y -= dy
+      self
+    end
   end
 end

metadata

@@ -1,15 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: math2d
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: '1.4'
 platform: ruby
 authors:
 - Ualace Henrique
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-08-25 00:00:00.000000000 Z
-dependencies: []
+date: 2022-04-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A collection of useful Mathematical and Vector tools in 2D space
 email:
 executables: []
@@ -38,7 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.16
+rubygems_version: 3.3.9
 signing_key:
 specification_version: 4
 summary: Math2D