vector2d 2.3.0 → 3.0.0

data/lib/vector2d/angles.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+class Vector2d
+  # The angle API. Radians are the native unit: every angle is measured
+  # counterclockwise from the positive x axis, and every method takes
+  # and returns radians unless its name says degrees.
+  #
+  # The degree methods are conversions layered on top, not a second
+  # angle API. Two general converters, .radians and .degrees, do the
+  # arithmetic once. Three degree variants build on them, each one the
+  # radian method with the angle converted: .from_degrees is
+  # .from_angle, #angle_in_degrees is #angle, and #rotate_degrees is
+  # #rotate. The rest of the angle API stays radians only. Convert at
+  # the call site for those.
+  #
+  #   Vector2d(2, 3).rotate_around(Vector2d(1, 1), Vector2d.radians(90))
+  #   # => Vector2d(-1.0,2.0)
+  #
+  #   Vector2d.degrees(Vector2d(2, 3).angle_to(Vector2d(4, 5)))
+  #   # => -4.9697..
+  #
+  # Porting note: pygame's rotate() and Unity's Vector2.Angle are in
+  # degrees, so those angles need .radians on the way in. Godot and
+  # Rust's glam are radians like this library, and their angles carry
+  # over unconverted.
+  module Angles
+    # The angle methods taking both vectors as arguments, and the
+    # conversions between radians and degrees. Extended into Vector2d,
+    # so they are called on the class.
+    #
+    #   Vector2d.angle_between(Vector2d(2, 3), Vector2d(4, 5))
+    #   # => 0.0867..
+    #
+    module ClassMethods
+      # Calculates the signed angle in radians from the first vector to
+      # the second, in the range -PI..PI. The angle is positive when the
+      # second vector is counterclockwise from the first, and reversing
+      # the arguments flips its sign.
+      #
+      #   v1 = Vector2d(2, 3)
+      #   v2 = Vector2d(4, 5)
+      #   Vector2d.angle_to(v1, v2) # => -0.0867..
+      #   Vector2d.angle_to(v2, v1) # => 0.0867..
+      #
+      # Only the directions matter, not the magnitudes. The zero vector
+      # has no direction, and the angle to or from it is zero.
+      #
+      #   Vector2d.angle_to(v1, Vector2d(0, 0)) # => 0.0
+      #
+      # @param vector1 [Vector2d] the vector the angle is measured from
+      # @param vector2 [Vector2d] the vector the angle is measured to
+      # @return [Float] the angle in radians, in -PI..PI
+      def angle_to(vector1, vector2)
+        Math.atan2(cross_product(vector1, vector2),
+                   dot_product(vector1, vector2))
+      end
+
+      # Calculates the unsigned angle between two vectors in radians, in
+      # the range 0..PI. This is the magnitude of .angle_to, so the
+      # order of the arguments does not matter.
+      #
+      #   v1 = Vector2d(2, 3)
+      #   v2 = Vector2d(4, 5)
+      #   Vector2d.angle_between(v1, v2) # => 0.0867..
+      #   Vector2d.angle_between(v2, v1) # => 0.0867..
+      #
+      # Only the directions matter, not the magnitudes. The zero vector
+      # has no direction, and the angle between it and anything is zero.
+      #
+      #   Vector2d.angle_between(v1, Vector2d(0, 0)) # => 0.0
+      #
+      # @param vector1 [Vector2d] one of the vectors
+      # @param vector2 [Vector2d] the other vector
+      # @return [Float] the angle in radians, in 0..PI
+      def angle_between(vector1, vector2)
+        angle_to(vector1, vector2).abs
+      end
+
+      # Converts an angle from degrees to radians, the unit the rest of
+      # the library speaks. The result is always a float.
+      #
+      #   Vector2d.radians(0)   # => 0.0
+      #   Vector2d.radians(90)  # => 1.5707..
+      #   Vector2d.radians(180) # => 3.1415..
+      #
+      # .degrees converts back.
+      #
+      #   Vector2d.degrees(Vector2d.radians(90)) # => 90.0
+      #
+      # Raises ArgumentError unless the angle is a real number.
+      # Complex numbers are not angles, and are rejected.
+      #
+      #   Vector2d.radians(Complex(1, 2)) # => ArgumentError
+      #
+      # @param degrees [Integer, Float, Rational, BigDecimal]
+      #   the angle in degrees
+      # @return [Float] the angle in radians
+      def radians(degrees)
+        coordinate(degrees).to_f * Math::PI / 180
+      end
+
+      # Converts an angle from radians to degrees, the inverse of
+      # .radians. The result is always a float.
+      #
+      #   Vector2d.degrees(0)            # => 0.0
+      #   Vector2d.degrees(Math::PI / 2) # => 90.0
+      #   Vector2d.degrees(Math::PI)     # => 180.0
+      #
+      # This is the conversion #angle_in_degrees applies to #angle, and
+      # the one to reach for with the angle methods that have no degree
+      # variant.
+      #
+      #   Vector2d.degrees(Vector2d(0, 1).angle) # => 90.0
+      #
+      # Raises ArgumentError unless the angle is a real number.
+      # Complex numbers are not angles, and are rejected.
+      #
+      #   Vector2d.degrees(Complex(1, 2)) # => ArgumentError
+      #
+      # @param radians [Integer, Float, Rational, BigDecimal]
+      #   the angle in radians
+      # @return [Float] the angle in degrees
+      def degrees(radians)
+        coordinate(radians).to_f * 180 / Math::PI
+      end
+
+      # Creates a vector from an angle in degrees, with an optional
+      # length. This is .from_angle with the angle put through
+      # .radians, and is the same in every other respect: angles are
+      # measured counterclockwise from the positive x axis, and
+      # coordinates are always floats.
+      #
+      #   Vector2d.from_degrees(0)       # => Vector2d(1.0,0.0)
+      #   Vector2d.from_degrees(45)      # => Vector2d(0.7071..,0.7071..)
+      #   Vector2d.from_degrees(45, 2.0) # => Vector2d(1.4142..,1.4142..)
+      #
+      # #angle_in_degrees takes the angle back.
+      #
+      #   Vector2d.from_degrees(90).angle_in_degrees # => 90.0
+      #
+      # Raises ArgumentError unless both arguments are real numbers.
+      #
+      #   Vector2d.from_degrees(Complex(1, 2)) # => ArgumentError
+      #
+      # @param angle [Integer, Float, Rational, BigDecimal] the angle in degrees
+      # @param length [Integer, Float, Rational, BigDecimal]
+      #   the length of the vector
+      # @return [Vector2d] a vector of the receiver's class
+      def from_degrees(angle, length = 1.0)
+        from_angle(radians(angle), length)
+      end
+    end
+
+    # Angle of vector.
+    #
+    #   Vector2d(2, 3).angle # => 0.9827..
+    #
+    # @return [Float] the angle in radians
+    def angle
+      Math.atan2(y, x)
+    end
+
+    # Signed angle in radians from this vector to another vector, in the
+    # range -PI..PI. The angle is positive when the other vector is
+    # counterclockwise from this one.
+    #
+    #   v1 = Vector2d(2, 3)
+    #   v2 = Vector2d(4, 5)
+    #   v1.angle_to(v2) # => -0.0867..
+    #   v2.angle_to(v1) # => 0.0867..
+    #
+    # Only the directions matter, not the magnitudes. The zero vector
+    # has no direction, and the angle to or from it is zero.
+    #
+    #   v1.angle_to(Vector2d(0, 0)) # => 0.0
+    #
+    # @!macro coercible
+    # @return [Float] the angle in radians, in -PI..PI
+    def angle_to(other)
+      v = coerce_vector(other)
+      self.class.angle_to(self, v)
+    end
+
+    # Unsigned angle in radians between this vector and another vector,
+    # in the range 0..PI. This is the magnitude of #angle_to, so it is
+    # the same in either direction.
+    #
+    #   v1 = Vector2d(2, 3)
+    #   v2 = Vector2d(4, 5)
+    #   v1.angle_between(v2) # => 0.0867..
+    #   v2.angle_between(v1) # => 0.0867..
+    #
+    # Only the directions matter, not the magnitudes. The zero vector
+    # has no direction, and the angle between it and anything is zero.
+    #
+    #   v1.angle_between(Vector2d(0, 0)) # => 0.0
+    #
+    # @!macro coercible
+    # @return [Float] the angle in radians, in 0..PI
+    def angle_between(other)
+      angle_to(other).abs
+    end
+    alias angle_with angle_between
+
+    # Polar coordinates of vector, as a [length, angle] array.
+    #
+    #   Vector2d(2, 3).to_polar # => [3.6055.., 0.9827..]
+    #
+    # Vector2d.from_angle takes the same pair back.
+    #
+    #   length, angle = Vector2d(2, 3).to_polar
+    #   Vector2d.from_angle(angle, length) # => Vector2d(2.0,3.0)
+    #
+    # @return [Array(Float, Float)] the length and the angle in radians
+    def to_polar
+      [length, angle]
+    end
+
+    # Rotates the vector around the origin. The angle is in radians, and
+    # a positive angle turns counterclockwise.
+    #
+    #   Vector2d(2, 3).rotate(Math::PI / 2) # => Vector2d(-3.0,2.0)
+    #
+    # Raises ArgumentError unless the angle is a real number.
+    #
+    #   Vector2d(2, 3).rotate(Complex(1, 2)) # => ArgumentError
+    #
+    # @param angle [Integer, Float, Rational, BigDecimal] the angle in radians
+    # @return [self]
+    def rotate(angle)
+      angle = coordinate(angle)
+      cos = Math.cos(angle)
+      sin = Math.sin(angle)
+      build((x * cos) - (y * sin), (x * sin) + (y * cos))
+    end
+
+    # Rotates the vector around another point. The center is coerced, so
+    # scalars work too. The angle is in radians, and a positive angle
+    # turns counterclockwise.
+    #
+    #   Vector2d(2, 1).rotate_around(Vector2d(1, 1), Math::PI / 2)
+    #   # => Vector2d(1.0,2.0)
+    #
+    # @!macro coercible
+    # @param angle [Integer, Float, Rational, BigDecimal] the angle in radians
+    # @return [self]
+    def rotate_around(center, angle)
+      center_v = coerce_vector(center)
+      (self - center_v).rotate(angle) + center_v
+    end
+
+    # Returns the vector rotated a quarter turn counterclockwise.
+    #
+    #   Vector2d(2, 3).perpendicular # => Vector2d(-3,2)
+    #
+    # Counterclockwise is the same positive direction #rotate turns in.
+    # Use #perpendicular_cw for the other one.
+    #
+    # @return [self]
+    def perpendicular
+      build(-y, x)
+    end
+
+    # Returns the vector rotated a quarter turn clockwise.
+    #
+    #   Vector2d(2, 3).perpendicular_cw # => Vector2d(3,-2)
+    #
+    # @return [self]
+    def perpendicular_cw
+      build(y, -x)
+    end
+
+    # Angle of the vector in degrees. This is #angle put through
+    # .degrees, and follows the same convention: angles are measured
+    # counterclockwise from the positive x axis, in the range
+    # -180..180.
+    #
+    #   Vector2d(1, 0).angle_in_degrees  # => 0.0
+    #   Vector2d(0, 1).angle_in_degrees  # => 90.0
+    #   Vector2d(2, 3).angle_in_degrees  # => 56.3099..
+    #   Vector2d(0, -1).angle_in_degrees # => -90.0
+    #
+    # Vector2d.from_degrees takes the angle back.
+    #
+    #   Vector2d.from_degrees(Vector2d(2, 3).angle_in_degrees, 5.0)
+    #   # => Vector2d(2.7735..,4.1602..)
+    #
+    # @return [Float] the angle in degrees, in -180..180
+    def angle_in_degrees
+      self.class.degrees(angle)
+    end
+
+    # Rotates the vector around the origin by an angle in degrees. This
+    # is #rotate with the angle put through .radians, and turns the
+    # same way: a positive angle turns counterclockwise.
+    #
+    #   Vector2d(2, 3).rotate_degrees(90) # => Vector2d(-3.0,2.0)
+    #
+    # The two agree exactly wherever .radians lands on the angle
+    # #rotate would have been given.
+    #
+    #   Vector2d(2, 3).rotate_degrees(90) == Vector2d(2, 3).rotate(Math::PI / 2)
+    #   # => true
+    #
+    # Raises ArgumentError unless the angle is a real number.
+    #
+    #   Vector2d(2, 3).rotate_degrees(Complex(1, 2)) # => ArgumentError
+    #
+    # @param angle [Integer, Float, Rational, BigDecimal] the angle in degrees
+    # @return [self]
+    def rotate_degrees(angle)
+      rotate(self.class.radians(angle))
+    end
+  end
+end

data/lib/vector2d/arithmetic.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+class Vector2d
+  # The operators. A scalar operand applies to both coordinates.
+  # Anything else is coerced into a vector and applied one axis at a
+  # time.
+  module Arithmetic
+    # Multiplies vectors.
+    #
+    #   Vector2d(1, 2) * Vector2d(2, 3) # => Vector2d(2, 6)
+    #   Vector2d(1, 2) * 2              # => Vector2d(2, 4)
+    #
+    # @!macro coercible
+    # @return [self]
+    def *(other)
+      calculate_each(:*, other)
+    end
+
+    # Divides vectors.
+    #
+    #   Vector2d(4, 2) / Vector2d(2, 1) # => Vector2d(2, 2)
+    #   Vector2d(4, 2) / 2              # => Vector2d(2, 1)
+    #
+    # @!macro coercible
+    # @return [self]
+    def /(other)
+      calculate_each(:/, other)
+    end
+
+    # Adds vectors.
+    #
+    #   Vector2d(1, 2) + Vector2d(2, 3) # => Vector2d(3, 5)
+    #   Vector2d(1, 2) + 2              # => Vector2d(3, 4)
+    #
+    # @!macro coercible
+    # @return [self]
+    def +(other)
+      calculate_each(:+, other)
+    end
+
+    # Subtracts vectors.
+    #
+    #   Vector2d(2, 3) - Vector2d(2, 1) # => Vector2d(0, 2)
+    #   Vector2d(4, 3) - 1              # => Vector2d(3, 2)
+    #
+    # @!macro coercible
+    # @return [self]
+    def -(other)
+      calculate_each(:-, other)
+    end
+
+    # Returns the vector reversed.
+    #
+    #   -Vector2d(2, 3) # => Vector2d(-2,-3)
+    #
+    # @return [self]
+    def -@
+      reverse
+    end
+
+    # Returns the vector unchanged.
+    #
+    #   +Vector2d(2, 3) # => Vector2d(2,3)
+    #
+    # @return [self]
+    def +@
+      self
+    end
+
+    # Reverses the vector.
+    #
+    #   Vector2d(2, 3).reverse # => Vector2d(-2,-3)
+    #
+    # @return [self]
+    def reverse
+      build(-x, -y)
+    end
+
+    private
+
+    # Is the value a number both coordinates can be combined with
+    # directly? Complex is Numeric, but it is not a coordinate.
+    def real_number?(value)
+      value.is_a?(Numeric) && value.real?
+    end
+
+    def calculate_each(method, other)
+      return build(x.send(method, other), y.send(method, other)) if real_number?(other)
+
+      v = coerce_vector(other)
+      build(
+        x.send(method, v.x),
+        y.send(method, v.y)
+      )
+    end
+  end
+end

data/lib/vector2d/comparison.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+class Vector2d
+  # Predicates relating two vectors, and the checks on coordinates that
+  # arithmetic can take out of range. Where #== compares exactly, the
+  # predicates here allow for floating point drift.
+  module Comparison
+    # Are the two vectors equal, give or take floating point drift?
+    # Arithmetic that should land on a given vector usually lands a few
+    # ulps off it instead, which #== reports as a difference.
+    #
+    #   v1 = Vector2d(0.1, 0.2) + Vector2d(0.2, 0.4)
+    #   v2 = Vector2d(0.3, 0.6)
+    #   v1                   # => Vector2d(0.30000000000000004,0.6000..)
+    #   v1 == v2             # => false
+    #   v1.approx_equal?(v2) # => true
+    #
+    # The other vector is coerced, unlike in #==, so anything .parse
+    # accepts is compared as a vector.
+    #
+    #   v1.approx_equal?([0.3, 0.6]) # => true
+    #   v1 == [0.3, 0.6]             # => false
+    #
+    # The default tolerance is the one #parallel? and #perpendicular?
+    # use, a few ulps scaled by the magnitude of the vectors, so the
+    # same amount of drift is absorbed whatever the coordinates are
+    # sized like. It covers rounding error, and nothing more.
+    #
+    #   big = Vector2d(1e8, 2e8)
+    #   big.approx_equal?(big.rotate(2 * Math::PI)) # => true
+    #   big.approx_equal?(Vector2d(1e8, 2.1e8))     # => false
+    #
+    # Pass a tolerance for anything looser. It is an absolute distance
+    # between the two vectors, and is not scaled.
+    #
+    #   v3 = Vector2d(2, 3)
+    #   v3.approx_equal?(Vector2d(2, 4), 1.5) # => true
+    #   v3.approx_equal?(Vector2d(2, 4), 0.5) # => false
+    #
+    # Note that this is not a replacement for #==. Approximate equality
+    # is not transitive, and vectors that are approximately equal do not
+    # have the same #hash.
+    #
+    # @!macro coercible
+    # @param tolerance [Integer, Float, Rational, BigDecimal, nil]
+    #   an absolute distance, or nil for the default scaled tolerance
+    # @return [Boolean]
+    def approx_equal?(other, tolerance = nil)
+      v = coerce_vector(other)
+      return distance(v) <= coordinate(tolerance) unless tolerance.nil?
+
+      near_zero?(distance(v), [1.0, length, v.length].max)
+    end
+
+    # Are the two vectors parallel? Vectors pointing in opposite
+    # directions are parallel too.
+    #
+    #   v = Vector2d(2, 3)
+    #   v.parallel?(Vector2d(4, 6))   # => true
+    #   v.parallel?(Vector2d(-4, -6)) # => true
+    #   v.parallel?(Vector2d(3, 2))   # => false
+    #
+    # Only the directions matter, not the magnitudes. The zero vector
+    # has no direction, and is parallel to everything.
+    #
+    #   v.parallel?(Vector2d(0, 0)) # => true
+    #
+    # @!macro coercible
+    # @return [Boolean]
+    def parallel?(other)
+      v = coerce_vector(other)
+      return true if zero? || v.zero?
+
+      near_zero?(cross_product(v), length * v.length)
+    end
+
+    # Are the two vectors linearly independent? This is the inverse of
+    # #parallel?, and matches Vector#independent? in the standard
+    # library.
+    #
+    #   v = Vector2d(2, 3)
+    #   v.independent?(Vector2d(3, 2))   # => true
+    #   v.independent?(Vector2d(4, 6))   # => false
+    #   v.independent?(Vector2d(-4, -6)) # => false
+    #
+    # The zero vector is parallel to everything, so nothing is
+    # independent of it.
+    #
+    #   v.independent?(Vector2d(0, 0)) # => false
+    #
+    # @!macro coercible
+    # @return [Boolean]
+    def independent?(other)
+      !parallel?(other)
+    end
+
+    # Do the two vectors point in opposite directions? Only the
+    # directions matter, not the magnitudes.
+    #
+    #   v = Vector2d(2, 3)
+    #   v.opposite?(Vector2d(-2, -3)) # => true
+    #   v.opposite?(Vector2d(-4, -6)) # => true
+    #   v.opposite?(Vector2d(4, 6))   # => false
+    #   v.opposite?(Vector2d(3, 2))   # => false
+    #
+    # Opposite vectors are parallel, but #parallel? does not care which
+    # way along the line the other vector points.
+    #
+    #   v.parallel?(Vector2d(-4, -6)) # => true
+    #
+    # The zero vector has no direction to be the opposite of, so unlike
+    # #parallel? and #perpendicular?, which it satisfies trivially,
+    # it is opposite to nothing.
+    #
+    #   v.opposite?(Vector2d(0, 0)) # => false
+    #
+    # @!macro coercible
+    # @return [Boolean]
+    def opposite?(other)
+      v = coerce_vector(other)
+      return false if zero? || v.zero?
+
+      parallel?(v) && dot_product(v).negative?
+    end
+
+    # Are the two vectors perpendicular to each other?
+    #
+    #   v = Vector2d(2, 3)
+    #   v.perpendicular?(Vector2d(-3, 2)) # => true
+    #   v.perpendicular?(Vector2d(3, 2))  # => false
+    #
+    # Only the directions matter, not the magnitudes. The zero vector
+    # has no direction, and is perpendicular to everything.
+    #
+    #   v.perpendicular?(Vector2d(0, 0)) # => true
+    #
+    # @!macro coercible
+    # @return [Boolean]
+    def perpendicular?(other)
+      v = coerce_vector(other)
+      return true if zero? || v.zero?
+
+      near_zero?(dot_product(v), length * v.length)
+    end
+
+    # Are both coordinates finite?
+    #
+    #   Vector2d(2, 3).finite?               # => true
+    #   Vector2d(2, Float::INFINITY).finite? # => false
+    #   Vector2d(2, Float::NAN).finite?      # => false
+    #
+    # @return [Boolean]
+    def finite?
+      x.finite? && y.finite?
+    end
+
+    # Is either coordinate NaN? Nothing else in the library produces
+    # one, but arithmetic on infinities does.
+    #
+    #   Vector2d(2, 3).nan?          # => false
+    #   Vector2d(2, Float::NAN).nan? # => true
+    #
+    #   (Vector2d(2, 3) * Float::INFINITY * 0).nan? # => true
+    #
+    # @return [Boolean]
+    def nan?
+      coordinate_nan?(x) || coordinate_nan?(y)
+    end
+
+    private
+
+    # Is the coordinate NaN? Only floats and decimals can be, the rest
+    # of Numeric has no answer to give.
+    def coordinate_nan?(value)
+      value.respond_to?(:nan?) && value.nan?
+    end
+
+    # Is a value close enough to zero to count as zero? The tolerance
+    # scales with the magnitudes the value was calculated from.
+    #
+    #   near_zero?(1e-14)      # => false
+    #   near_zero?(1e-14, 1e6) # => true
+    #
+    def near_zero?(value, scale = 1.0)
+      value.abs < (4 * Float::EPSILON * scale)
+    end
+  end
+end