math2d 1.3 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d41532de5491da28b9de631463ae49ab77b12bd17ecac7f7efacf28e508a5d9
-  data.tar.gz: 763fe0ac3840a0cb9b241514c8baac852a9388059428e89fce516116ab659b02
+  metadata.gz: 34a1c8daaf45027dc42765be7a12a631038b42bfb3454d68da26eb99e763cacd
+  data.tar.gz: 0b3e5533e79a80877806416dffb8c055f6164d5b391eea3ba0764589eb59bbcd
 SHA512:
-  metadata.gz: ea01a56166ba411a2d015d67fb45224f072dfc6a2d57e00683ebc40216aa3dfae88e9b7a4a7cc057beae2eed42dd6a97eb5fc7553ed51c4593564bdc92997d86
-  data.tar.gz: c911d1c8bdc54a010588c07294601b1e9e5549bd35c8a76bc8e461683bdb09e37a01bf5d2fc98867e89795b45c420bb42f426b18e9b4c94cf39151fd2947f824
+  metadata.gz: fd195200c4e96cac60591821c73fa96b73e3cf3902dfff3f77191c4fd70ecad42c590dd92df7d9b90250647c6a02bf847f6a0b9f951f4def7544fe3bb9d8457e
+  data.tar.gz: b578724ee4a68f9951a7fb5d31f0e10dcb9700d3b9b70496f23afc6c4ef11c0cc674a28c54fa83d89fe72745219b3f1b74b9cc685a1bdae5f16d62417eec1415

data/lib/math2d/utils2d.rb

@@ -13,11 +13,11 @@ 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_deg+.
-    DEG2RAD      = Math::PI / 180
-    # Multiplication constant to convert a value in degrees to radians
+    # 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.
@@ -25,7 +25,7 @@ module Math2D
     # @param [Numeric] angle
     # @return [Float]
     def self.to_deg(angle)
-      angle * DEG2RAD
+      angle * RAD2DEG
     end
 
     # Returns +angle+ degrees in radians.
@@ -33,7 +33,7 @@ module Math2D
     # @param [Numeric] angle
     # @return [Float]
     def self.to_rad(angle)
-      angle * RAD2DEG
+      angle * DEG2RAD
     end
 
     # Returns the distance between two cartesian points.
@@ -142,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>]
@@ -156,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,53 +101,62 @@ 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)
-
-      Vector2D.new(@x / other, @y / other)
+      clone.divide_by!(other)
     end
 
+    # Compares +self+ and +other+ according to their components.
+    #
+    # @param [Vector2D] other
+    # @return [Boolean]
     def ==(other)
       (@x == other.x) && (@y == other.y)
     end
@@ -162,6 +192,8 @@ module Math2D
       (@x**2) + (@y**2)
     end
 
+    alias magnitude2 squared
+
     # Returns the magnitude of +self+.
     #
     # @return [Float]
@@ -171,6 +203,16 @@ module Math2D
 
     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
@@ -189,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
 
@@ -223,23 +265,35 @@ 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?
+      times!(new_mag / mag)
     end
 
-    # Normalizes +self+ (set the magnitude to 1).
+    alias magnitude! set_magnitude
+
+    # Normalizes +self+ (set the magnitude to 1) and returns a new vector.
     # +unit+ is an alias for this method.
     #
-    # @return [Vector2D]
+    # @return [Vector2D] new vector
     def normalize
-      set_magnitude(1)
+      clone.set_magnitude(1)
     end
 
     alias unit normalize
 
+    # Normalizes +self+ (set the magnitude to 1) *in place*.
+    # +unit!+ is an alias for this method.
+    #
+    # @return [Vector2D] modified self
+    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.
     #
@@ -288,39 +342,64 @@ module Math2D
     # @param [Vector2D] other
     # @return [Boolean]
     def opposite?(other)
-      dot(other) < 0
+      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
+      self
     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)
+      self
     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+.
@@ -340,26 +419,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, y)
+      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 * refractive_index * (1.0 - dot_prod * dot_prod)
+      k = 1.0 - refractive_index.abs2 * (1.0 - dot_prod.abs2)
       return Vector2D.zero if k.negative?
 
-      x = refractive_index * @x - (refractive_index * dot_prod * Math.sqrt(k)) * other.x
-      y = refractive_index * @y - (refractive_index * dot_prod * Math.sqrt(k)) * other.y
+      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
 
@@ -385,6 +465,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.
     #
@@ -395,5 +495,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.3'
+  version: 1.4.1
 platform: ruby
 authors:
 - Ualace Henrique
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-02-10 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.3.3
+rubygems_version: 3.3.9
 signing_key:
 specification_version: 4
 summary: Math2D