vector2d 2.3.0 → 3.0.0

data/lib/vector2d/dimensions.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+class Vector2d
+  # The vector as a rectangle. Vector2d grew out of handling image
+  # dimensions, and these methods describe a size and fit one inside
+  # another. All of them compare coordinates by magnitude, so a
+  # negative vector describes the same rectangle as its positive twin.
+  module Dimensions
+    # Area covered by the vector, the product of its coordinates.
+    # Coordinates are taken by magnitude, as in #aspect_ratio, so the
+    # area is never negative.
+    #
+    #   Vector2d(2, 3).area  # => 6
+    #   Vector2d(-2, 3).area # => 6
+    #
+    # A vector without width or height covers nothing.
+    #
+    #   Vector2d(2, 0).area # => 0
+    #
+    # @return [Integer, Float, Rational, BigDecimal]
+    def area
+      (x * y).abs
+    end
+
+    # Aspect ratio of vector.
+    #
+    #   Vector2d(2, 3).aspect_ratio # => 0.6666..
+    #
+    # A vector without height has no aspect ratio, so ArgumentError is
+    # raised.
+    #
+    #   Vector2d(2, 0).aspect_ratio # => ArgumentError
+    #   Vector2d(0, 0).aspect_ratio # => ArgumentError
+    #
+    # @return [Float]
+    def aspect_ratio
+      raise ArgumentError, "the zero vector has no aspect ratio" if zero?
+      raise ArgumentError, "#{inspect} has no aspect ratio, y is zero" if y.zero?
+
+      (x.to_f / y).abs
+    end
+
+    # Is the vector wider than it is tall?
+    #
+    #   Vector2d(3, 2).landscape? # => true
+    #   Vector2d(2, 3).landscape? # => false
+    #   Vector2d(2, 2).landscape? # => false
+    #
+    # Coordinates are compared by magnitude, as in #aspect_ratio.
+    #
+    #   Vector2d(-3, 2).landscape? # => true
+    #
+    # @return [Boolean]
+    def landscape?
+      x.abs > y.abs
+    end
+
+    # Is the vector taller than it is wide?
+    #
+    #   Vector2d(2, 3).portrait? # => true
+    #   Vector2d(3, 2).portrait? # => false
+    #   Vector2d(2, 2).portrait? # => false
+    #
+    # Coordinates are compared by magnitude, as in #aspect_ratio.
+    #
+    #   Vector2d(2, -3).portrait? # => true
+    #
+    # @return [Boolean]
+    def portrait?
+      x.abs < y.abs
+    end
+
+    # Is the vector as wide as it is tall?
+    #
+    #   Vector2d(2, 2).square? # => true
+    #   Vector2d(2, 3).square? # => false
+    #
+    # Coordinates are compared by magnitude, as in #aspect_ratio.
+    # Exactly one of #square?, #landscape? and #portrait? holds for any
+    # vector.
+    #
+    #   Vector2d(-2, 2).square? # => true
+    #
+    # Unlike #aspect_ratio, these three don't single out the zero
+    # vector. It is square.
+    #
+    #   Vector2d(0, 0).square? # => true
+    #
+    # @return [Boolean]
+    def square?
+      x.abs == y.abs
+    end
+
+    # Scales the vector to fit inside another vector, retaining the
+    # aspect ratio.
+    #
+    #   vector = Vector2d(20, 10)
+    #   vector.fit(Vector2d(10, 10)) # => Vector2d(10.0,5.0)
+    #   vector.fit(Vector2d(20, 20)) # => Vector2d(20.0,10.0)
+    #   vector.fit(Vector2d(40, 40)) # => Vector2d(40.0,20.0)
+    #
+    # Pass <tt>upscale: false</tt> to scale down only, leaving a vector
+    # that already fits unchanged.
+    #
+    #   vector.fit(Vector2d(40, 40), upscale: false) # => Vector2d(20,10)
+    #   vector.fit(Vector2d(10, 10), upscale: false) # => Vector2d(10.0,5.0)
+    #
+    # The constraint applies to the magnitude of each coordinate, and
+    # the vector keeps its direction.
+    #
+    #   Vector2d(-20, 10).fit(Vector2d(5, 5)) # => Vector2d(-5.0,2.5)
+    #
+    # Note: Either axis will be disregarded if zero or nil. This is a
+    # feature, not a bug. A constraint that is zero on both axes leaves
+    # the vector unchanged.
+    #
+    #   Vector2d(20, 10).fit(Vector2d(0, 0)) # => Vector2d(20,10)
+    #
+    # The zero vector has no direction, and is returned unchanged.
+    #
+    #   Vector2d(0, 0).fit(Vector2d(10, 10)) # => Vector2d(0,0)
+    #
+    # @!macro coercible
+    # @param upscale [Boolean] whether to scale a vector that already
+    #   fits up to the constraint
+    # @return [self]
+    def fit(other, upscale: true)
+      scale_by(fit_factors(coerce_vector(other)).min, upscale: upscale)
+    end
+
+    # Does the vector already fit inside another vector? True whenever
+    # <tt>fit(other, upscale: false)</tt> would leave it unchanged.
+    #
+    #   constraint = Vector2d(20, 20)
+    #   Vector2d(20, 10).fits?(constraint) # => true
+    #   Vector2d(40, 10).fits?(constraint) # => false
+    #
+    # A vector that exactly matches the constraint fits.
+    #
+    #   Vector2d(20, 20).fits?(constraint) # => true
+    #
+    # Coordinates are compared by magnitude, as in #fit.
+    #
+    #   Vector2d(-20, 10).fits?(constraint) # => true
+    #
+    # Note: Either axis will be disregarded if zero or nil, as in #fit.
+    # An axis that doesn't constrain can't be overflowed either.
+    #
+    #   Vector2d(40, 10).fits?(Vector2d(0, 20)) # => true
+    #
+    # The zero vector has no size, and fits inside anything.
+    #
+    #   Vector2d(0, 0).fits?(constraint) # => true
+    #
+    # @!macro coercible
+    # @return [Boolean]
+    def fits?(other)
+      factor = fit_factors(coerce_vector(other)).min
+      factor.nil? || factor >= 1
+    end
+
+    # Scales the vector to cover another vector, retaining the aspect
+    # ratio. Where #fit scales until the vector is contained by the
+    # constraint, #cover scales until it contains the constraint.
+    #
+    #   constraint = Vector2d(5, 5)
+    #   Vector2d(20, 10).cover(constraint) # => Vector2d(10.0,5.0)
+    #   Vector2d(10, 20).cover(constraint) # => Vector2d(5.0,10.0)
+    #
+    # Pass <tt>upscale: false</tt> to scale down only, leaving a vector
+    # that already covers the constraint unchanged.
+    #
+    #   Vector2d(20, 10).cover(Vector2d(40, 40), upscale: false)
+    #   # => Vector2d(20,10)
+    #
+    # As in #fit, coordinates are constrained by magnitude and the
+    # vector keeps its direction.
+    #
+    #   Vector2d(-20, 10).cover(constraint) # => Vector2d(-10.0,5.0)
+    #
+    # Note: Either axis will be disregarded if zero or nil, as in #fit.
+    # This is a feature, not a bug.
+    #
+    #   Vector2d(0, 10).cover(constraint) # => Vector2d(0.0,5.0)
+    #   Vector2d(20, 10).cover(Vector2d(0, 0)) # => Vector2d(20,10)
+    #
+    # The zero vector has no direction, and is returned unchanged.
+    #
+    #   Vector2d(0, 0).cover(Vector2d(5, 5)) # => Vector2d(0,0)
+    #
+    # @!macro coercible
+    # @param upscale [Boolean] whether to scale a vector that already
+    #   covers up to the constraint
+    # @return [self]
+    def cover(other, upscale: true)
+      scale_by(fit_factors(coerce_vector(other)).max, upscale: upscale)
+    end
+
+    # Does the vector already cover another vector? True whenever
+    # #cover would shrink the vector or leave it alone, rather than
+    # scaling it up. This is the predicate to #cover that #fits? is to
+    # #fit.
+    #
+    #   constraint = Vector2d(5, 5)
+    #   Vector2d(20, 10).covers?(constraint) # => true
+    #   Vector2d(20, 1).covers?(constraint)  # => false
+    #
+    # Coordinates are compared by magnitude, as in #cover.
+    #
+    #   Vector2d(-20, 10).covers?(constraint) # => true
+    #
+    # Note: Either axis will be disregarded if zero or nil, as in
+    # #cover, so a vector flat on one axis still counts as covering.
+    #
+    #   Vector2d(0, 10).covers?(constraint)  # => true
+    #   Vector2d(0, 0).covers?(constraint)   # => true
+    #
+    # @!macro coercible
+    # @return [Boolean]
+    def covers?(other)
+      factor = fit_factors(coerce_vector(other)).max
+      factor.nil? || factor <= 1
+    end
+
+    # @deprecated Use #cover instead.
+    #
+    # @!macro coercible
+    # @return [self]
+    def fit_either(other)
+      warn_deprecated("Vector2d#fit_either is deprecated. Use #cover instead.")
+      cover(other)
+    end
+
+    # @deprecated Use <tt>other.fit(self, upscale: false)</tt> instead.
+    #
+    # Scales down the given vector unless it fits inside.
+    #
+    #   vector = Vector2d(20, 20)
+    #   vector.contain(Vector2d(10, 10)) # => Vector2d(10,10)
+    #   vector.contain(Vector2d(40, 20)) # => Vector2d(20.0,10.0)
+    #   vector.contain(Vector2d(20, 40)) # => Vector2d(10.0,20.0)
+    #
+    # Coordinates are compared by magnitude, so negative vectors are
+    # scaled the same way and keep their direction.
+    #
+    #   vector.contain(Vector2d(-40, 20)) # => Vector2d(-20.0,10.0)
+    #
+    # An axis that is zero is unconstrained, as in #fit, so the zero
+    # vector contains anything.
+    #
+    #   Vector2d(0, 0).contain(Vector2d(40, 20)) # => Vector2d(40,20)
+    #
+    # @!macro coercible
+    # @return [Vector2d] a vector of the argument's class, not of this one
+    def contain(other)
+      warn_deprecated("Vector2d#contain is deprecated. " \
+                      "Use `other.fit(self, upscale: false)` instead.")
+      coerce_vector(other).fit(self, upscale: false)
+    end
+
+    # @deprecated Use #fit instead.
+    #
+    # @!macro coercible
+    # @return [self]
+    def constrain_both(other)
+      warn_deprecated("Vector2d#constrain_both is deprecated. Use #fit instead.")
+      fit(other)
+    end
+
+    # @deprecated Use #cover instead.
+    #
+    # @!macro coercible
+    # @return [self]
+    def constrain_one(other)
+      warn_deprecated("Vector2d#constrain_one is deprecated. Use #cover instead.")
+      cover(other)
+    end
+
+    protected
+
+    # Magnitudes of the scale factor for each axis, disregarding axes
+    # that don't constrain the vector.
+    def fit_factors(other)
+      scale = other.to_f_vector / self
+      scale.to_a.select { |s| s.finite? && !s.zero? }.map(&:abs)
+    end
+
+    # Scales the vector by the given factor. An unconstrained vector,
+    # which has no factor, is returned unchanged, as is one that would
+    # grow when +upscale+ is false.
+    def scale_by(factor, upscale:)
+      return self if factor.nil? || (!upscale && factor >= 1)
+
+      self * factor
+    end
+  end
+end

data/lib/vector2d/interpolation.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+class Vector2d
+  # Interpolation between two vectors, and stepping from one toward
+  # another.
+  module Interpolation
+    # Linearly interpolates between this vector and another vector.
+    #
+    #   v1 = Vector2d(0, 0)
+    #   v2 = Vector2d(10, 20)
+    #   v1.lerp(v2, 0.0)  # => Vector2d(0.0,0.0)
+    #   v1.lerp(v2, 0.25) # => Vector2d(2.5,5.0)
+    #   v1.lerp(v2, 1.0)  # => Vector2d(10.0,20.0)
+    #
+    # The amount is not clamped to 0..1. Values outside that range
+    # extrapolate past the end points.
+    #
+    #   v1.lerp(v2, 2.0)  # => Vector2d(20.0,40.0)
+    #   v1.lerp(v2, -0.5) # => Vector2d(-5.0,-10.0)
+    #
+    # Raises ArgumentError unless the amount is a real number. One
+    # amount applies to both axes.
+    #
+    #   v1.lerp(v2, Vector2d(0.25, 0.5)) # => ArgumentError
+    #
+    # @!macro coercible
+    # @param amount [Integer, Float, Rational, BigDecimal]
+    #   the position along the segment
+    # @return [self]
+    def lerp(other, amount)
+      v = coerce_vector(other)
+      amount = coordinate(amount)
+      build(interpolate(x, v.x, amount), interpolate(y, v.y, amount))
+    end
+
+    # Returns the amount #lerp would need to land on a value, the
+    # position of that value along the segment from this vector to
+    # another one. This is the inverse of #lerp.
+    #
+    #   v1 = Vector2d(0, 0)
+    #   v2 = Vector2d(10, 20)
+    #   v1.inverse_lerp(v2, Vector2d(2.5, 5.0)) # => 0.25
+    #   v1.inverse_lerp(v2, v1)                 # => 0.0
+    #   v1.inverse_lerp(v2, v2)                 # => 1.0
+    #
+    # The result is a scalar, one amount for both axes, matching the
+    # single amount #lerp takes.
+    #
+    #   v1.lerp(v2, v1.inverse_lerp(v2, Vector2d(2.5, 5.0))) # => Vector2d(2.5,5.0)
+    #
+    # The value does not have to lie on the segment. Anything off it is
+    # projected onto the line through the end points first, so the
+    # result is the position of the nearest point on that line.
+    #
+    #   v1.inverse_lerp(v2, Vector2d(5, 0)) # => 0.1
+    #
+    # The result is not clamped to 0..1, the same way the amount #lerp
+    # takes is not. Values beyond the end points fall outside it.
+    #
+    #   v1.inverse_lerp(v2, Vector2d(20, 40))  # => 2.0
+    #   v1.inverse_lerp(v2, Vector2d(-5, -10)) # => -0.5
+    #
+    # A segment between two identical vectors has no length to measure
+    # along, and no amount reaches anything but its own end point. Zero
+    # is returned.
+    #
+    #   v1.inverse_lerp(v1, Vector2d(2.5, 5.0)) # => 0.0
+    #
+    # @!macro coercible
+    # @param value [Vector2d, Array, String, Hash, Integer, Float, Rational,
+    #   BigDecimal, ::Vector, ::Matrix] the value to locate, anything
+    #   Vector2d.parse accepts
+    # @return [Float] the amount #lerp would take to reach the value
+    def inverse_lerp(other, value)
+      segment = coerce_vector(other) - self
+      return 0.0 if segment.zero?
+
+      (coerce_vector(value) - self).dot_product(segment).to_f / segment.length_squared
+    end
+
+    # Spherically interpolates between this vector and another vector.
+    # The vector turns through the angle between the two, while the
+    # length is interpolated linearly. The other vector is coerced, so
+    # scalars work too.
+    #
+    #   v1 = Vector2d(2, 0)
+    #   v2 = Vector2d(0, 4)
+    #   v1.slerp(v2, 0.5) # => Vector2d(2.1213..,2.1213..)
+    #
+    # Where #lerp moves along the straight line between the two
+    # vectors, #slerp moves along the arc between them, so the length
+    # follows the end points instead of cutting the corner.
+    #
+    #   v1.lerp(v2, 0.5).length  # => 2.2360..
+    #   v1.slerp(v2, 0.5).length # => 3.0
+    #
+    # Vectors pointing in opposite directions are half a turn apart
+    # either way around. The turn is counterclockwise, the direction
+    # #rotate takes a positive angle in.
+    #
+    #   half = Vector2d(2, 0).slerp(Vector2d(-2, 0), 0.5)
+    #   half.angle  # => 1.5707..
+    #   half.length # => 2.0
+    #
+    # The zero vector has no direction to turn from or to, and there is
+    # no arc to follow. #lerp is used instead.
+    #
+    #   Vector2d(0, 0).slerp(v2, 0.5) # => Vector2d(0.0,2.0)
+    #
+    # The amount is not clamped to 0..1, and behaves as it does in
+    # #lerp. Values outside that range keep turning past the end
+    # points.
+    #
+    #   v1.slerp(v2, 2.0).angle # => 3.1415..
+    #
+    # @!macro coercible
+    # @param amount [Integer, Float, Rational, BigDecimal]
+    #   the position along the segment
+    # @return [self]
+    def slerp(other, amount)
+      v = coerce_vector(other)
+      amount = coordinate(amount)
+      return lerp(v, amount) if zero? || v.zero?
+
+      rotate(slerp_angle(v) * amount) *
+        (interpolate(length, v.length, amount) / length)
+    end
+
+    # Returns the point halfway between this vector and another vector.
+    #
+    #   v1 = Vector2d(0, 0)
+    #   v2 = Vector2d(10, 20)
+    #   v1.midpoint(v2) # => Vector2d(5.0,10.0)
+    #
+    # @!macro coercible
+    # @return [self]
+    def midpoint(other)
+      lerp(other, 0.5)
+    end
+
+    # Moves this vector toward another vector by a fixed distance,
+    # stopping at the target instead of overshooting it. The target is
+    # coerced, so scalars work too.
+    #
+    #   v1 = Vector2d(0, 0)
+    #   v2 = Vector2d(10, 0)
+    #   v1.move_toward(v2, 2)  # => Vector2d(2.0,0.0)
+    #   v1.move_toward(v2, 20) # => Vector2d(10,0)
+    #
+    # Where #lerp takes a fraction of the way there, this takes a
+    # distance, so the step is the same size however far off the target
+    # is.
+    #
+    # A negative distance moves away from the target, and has nothing
+    # to overshoot.
+    #
+    #   v1.move_toward(v2, -2) # => Vector2d(-2.0,0.0)
+    #
+    # There is nowhere to move when the vector is already at the
+    # target, whatever the distance. The target is returned.
+    #
+    #   v2.move_toward(v2, 2) # => Vector2d(10,0)
+    #
+    # @!macro coercible
+    # @param distance [Integer, Float, Rational, BigDecimal] how far to move
+    # @return [self]
+    def move_toward(target, distance)
+      v = coerce_vector(target)
+      distance = coordinate(distance)
+      delta = build(v.x - x, v.y - y)
+      return build(v.x, v.y) if delta.zero? || distance >= delta.length
+
+      self + delta.resize(distance)
+    end
+
+    private
+
+    # The angle #slerp turns through. Vectors pointing in opposite
+    # directions are half a turn apart either way around, and the
+    # counterclockwise one is taken.
+    def slerp_angle(other)
+      return Math::PI if parallel?(other) && dot_product(other).negative?
+
+      angle_to(other)
+    end
+
+    def interpolate(start, finish, amount)
+      start + ((finish - start) * amount)
+    end
+  end
+end