vector2d 2.3.0 → 3.0.0

data/lib/vector2d/projection.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+class Vector2d
+  # Products of two vectors, and the projection, reflection and
+  # refraction built on them.
+  module Projection
+    # The products taking both vectors as arguments. Extended into
+    # Vector2d, so they are called on the class.
+    #
+    #   Vector2d.dot_product(Vector2d(2, 1), Vector2d(2, 3)) # => 7
+    #
+    module ClassMethods
+      # Calculates dot product of two vectors.
+      #
+      #   v1 = Vector2d(2, 1)
+      #   v2 = Vector2d(2, 3)
+      #   Vector2d.dot_product(v1, v2) # => 7
+      #
+      # @param vector1 [Vector2d] one of the vectors
+      # @param vector2 [Vector2d] the other vector
+      # @return [Integer, Float, Rational, BigDecimal] a scalar
+      def dot_product(vector1, vector2)
+        (vector1.x * vector2.x) + (vector1.y * vector2.y)
+      end
+
+      # Calculates cross product of two vectors.
+      #
+      #   v1 = Vector2d(2, 1)
+      #   v2 = Vector2d(2, 3)
+      #   Vector2d.cross_product(v1, v2) # => 4
+      #
+      # @param vector1 [Vector2d] the vector the product is measured from
+      # @param vector2 [Vector2d] the vector the product is measured to
+      # @return [Integer, Float, Rational, BigDecimal] a scalar
+      def cross_product(vector1, vector2)
+        (vector1.x * vector2.y) - (vector1.y * vector2.x)
+      end
+    end
+
+    # Dot product of this vector and another vector.
+    #
+    #   v1 = Vector2d(2, 1)
+    #   v2 = Vector2d(2, 3)
+    #   v1.dot_product(v2) # => 7
+    #
+    # @!macro coercible
+    # @return [Integer, Float, Rational, BigDecimal] a scalar
+    def dot_product(other)
+      v = coerce_vector(other)
+      self.class.dot_product(self, v)
+    end
+    alias inner_product dot_product
+    alias dot dot_product
+
+    # Cross product of this vector and another vector. In two
+    # dimensions this is a scalar, the z component of the equivalent
+    # three dimensional cross product. Vector#cross_product returns a
+    # perpendicular vector instead, which is #perpendicular here.
+    #
+    #   v1 = Vector2d(2, 1)
+    #   v2 = Vector2d(2, 3)
+    #   v1.cross_product(v2) # => 4
+    #
+    # @!macro coercible
+    # @return [Integer, Float, Rational, BigDecimal] a scalar
+    def cross_product(other)
+      v = coerce_vector(other)
+      self.class.cross_product(self, v)
+    end
+
+    # Vector projection of this vector onto another vector. The
+    # argument is coerced, so scalars work too.
+    #
+    #   v1 = Vector2d(2, 3)
+    #   v2 = Vector2d(4, 0)
+    #   v1.project(v2) # => Vector2d(2.0,0.0)
+    #
+    # The zero vector has no direction, and there is nothing to project
+    # onto. The zero vector is returned.
+    #
+    #   v1.project(Vector2d(0, 0)) # => Vector2d(0.0,0.0)
+    #
+    # @!macro coercible
+    # @return [self]
+    def project(other)
+      v = coerce_vector(other)
+      return build(0.0, 0.0) if v.zero?
+
+      scale = dot_product(v).to_f / v.length_squared
+      build(v.x * scale, v.y * scale)
+    end
+
+    # Vector rejection of this vector from another vector, the component
+    # left over when the projection is subtracted.
+    #
+    #   v1 = Vector2d(2, 3)
+    #   v2 = Vector2d(4, 0)
+    #   v1.reject(v2) # => Vector2d(0.0,3.0)
+    #
+    # The zero vector has no direction, and nothing is projected away.
+    #
+    #   v1.reject(Vector2d(0, 0)) # => Vector2d(2.0,3.0)
+    #
+    # @!macro coercible
+    # @return [self]
+    def reject(other)
+      self - project(other)
+    end
+
+    # Scalar projection of this vector onto another vector, the signed
+    # length of the projection. It is negative when the vectors point in
+    # opposite directions.
+    #
+    #   v1 = Vector2d(2, 3)
+    #   v2 = Vector2d(4, 0)
+    #   v1.scalar_projection(v2)              # => 2.0
+    #   v1.scalar_projection(Vector2d(-4, 0)) # => -2.0
+    #
+    # The zero vector has no direction, and there is nothing to project
+    # onto. The scalar projection is zero.
+    #
+    #   v1.scalar_projection(Vector2d(0, 0)) # => 0.0
+    #
+    # @!macro coercible
+    # @return [Float] a scalar, the signed length of the projection
+    def scalar_projection(other)
+      v = coerce_vector(other)
+      return 0.0 if v.zero?
+
+      dot_product(v) / v.length
+    end
+
+    # Reflects this vector about the line perpendicular to the normal,
+    # the way a ray bounces off a surface. The normal is normalized
+    # internally, so it can be of any length.
+    #
+    #   vector = Vector2d(2, 3)
+    #   vector.reflect(Vector2d(0, 1)) # => Vector2d(2.0,-3.0)
+    #   vector.reflect(Vector2d(0, 5)) # => Vector2d(2.0,-3.0)
+    #
+    # The zero vector has no direction, and defines no surface to
+    # reflect off. Nothing is reflected, and the vector is returned.
+    #
+    #   vector.reflect(Vector2d(0, 0)) # => Vector2d(2.0,3.0)
+    #
+    # @!macro coercible
+    # @return [self]
+    def reflect(normal)
+      v = coerce_vector(normal)
+      return to_f_vector if v.zero?
+
+      n = v.normalize
+      self - (n * (2 * dot_product(n)))
+    end
+
+    # Refracts this vector through a surface with the given normal and
+    # ratio of refractive indices, the way a ray bends entering a
+    # different medium. The normal is normalized internally, so it can
+    # be of any length.
+    #
+    #   ray = Vector2d(1, -1).normalize
+    #   ray.refract(Vector2d(0, 1), 0.5) # => Vector2d(0.3535..,-0.9354..)
+    #   ray.refract(Vector2d(0, 5), 0.5) # => Vector2d(0.3535..,-0.9354..)
+    #
+    # A ratio of one leaves the ray on its course.
+    #
+    #   ray.refract(Vector2d(0, 1), 1.0) # => Vector2d(0.7071..,-0.7071..)
+    #
+    # Past the critical angle the ray does not cross the surface at all.
+    # This is total internal reflection, and the zero vector is
+    # returned.
+    #
+    #   ray.refract(Vector2d(0, 1), 2.0) # => Vector2d(0.0,0.0)
+    #
+    # The zero vector has no direction, and defines no surface to
+    # refract through. Nothing is refracted, and the vector is returned.
+    #
+    #   ray.refract(Vector2d(0, 0), 0.5) # => Vector2d(0.7071..,-0.7071..)
+    #
+    # Raises ArgumentError unless the ratio is a real number.
+    #
+    #   ray.refract(Vector2d(0, 1), Complex(1, 2)) # => ArgumentError
+    #
+    # @!macro coercible
+    # @param refractive_index [Integer, Float, Rational, BigDecimal]
+    #   the ratio of refractive indices
+    # @return [self]
+    def refract(normal, refractive_index)
+      v = coerce_vector(normal)
+      eta = coordinate(refractive_index)
+      return to_f_vector if v.zero?
+
+      refract_through(v.normalize, eta)
+    end
+
+    private
+
+    # Refracts through a normalized normal. A negative discriminant is
+    # total internal reflection, where no refracted ray exists.
+    def refract_through(normal, eta)
+      cosine = dot_product(normal)
+      k = 1 - ((eta * eta) * (1 - (cosine * cosine)))
+      return build(0.0, 0.0) if k.negative?
+
+      (self * eta) - (normal * ((eta * cosine) + Math.sqrt(k)))
+    end
+  end
+end

data/lib/vector2d/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 class Vector2d
-  VERSION = "2.3.0"
+  # The version of the gem.
+  VERSION = "3.0.0"
 end

data/lib/vector2d.rb

@@ -1,86 +1,198 @@
 # frozen_string_literal: true
 
-require "vector2d/calculations"
-require "vector2d/coercions"
-require "vector2d/fitting"
-require "vector2d/properties"
-require "vector2d/transformations"
-require "vector2d/version"
-
-class Vector2d
-  extend Vector2d::Calculations::ClassMethods
-  include Vector2d::Calculations
-  include Vector2d::Coercions
-  include Vector2d::Fitting
-  include Vector2d::Properties
-  include Vector2d::Transformations
-
-  class << self
-    # Creates a new vector.
-    # The following examples are all valid:
-    #
-    #   Vector2d.parse(150, 100)
-    #   Vector2d.parse(150.0, 100.0)
-    #   Vector2d.parse("150x100")
-    #   Vector2d.parse("150.0x100.0")
-    #   Vector2d.parse([150,100})
-    #   Vector2d.parse({x: 150, y: 100})
-    #   Vector2d.parse({"x" => 150.0, "y" => 100.0})
-    #   Vector2d.parse(Vector2d(150, 100))
-    def parse(arg, second_arg = nil)
-      if second_arg.nil?
-        parse_single_arg(arg)
-      else
-        new(arg, second_arg)
-      end
-    end
-
-    private
-
-    def parse_single_arg(arg)
-      return arg if arg.is_a?(Vector2d)
-      return parse(*arg) if arg.is_a?(Array)
-      return parse_str(arg) if arg.is_a?(String)
-      return parse_hash(arg.dup) if arg.is_a?(Hash)
-
-      new(arg, arg)
-    end
+# The one place the types Vector2d.parse accepts are written out. Every
+# parameter that is coerced into a vector takes this union.
+#
+# @!macro [new] coercible
+#  @param $1 [Vector2d, Array, String, Hash, Integer, Float, Rational,
+#    BigDecimal, ::Vector, ::Matrix] anything Vector2d.parse accepts
 
-    def parse_hash(hash)
-      hash[:x] ||= hash["x"] if hash.key?("x")
-      hash[:y] ||= hash["y"] if hash.key?("y")
-      new(hash[:x], hash[:y])
-    end
+require_relative "vector2d/angles"
+require_relative "vector2d/arithmetic"
+require_relative "vector2d/comparison"
+require_relative "vector2d/componentwise"
+require_relative "vector2d/constructors"
+require_relative "vector2d/conversions"
+require_relative "vector2d/coordinates"
+require_relative "vector2d/deprecation"
+require_relative "vector2d/dimensions"
+require_relative "vector2d/interpolation"
+require_relative "vector2d/lengths"
+require_relative "vector2d/matrix_interop"
+require_relative "vector2d/parsing"
+require_relative "vector2d/projection"
+require_relative "vector2d/version"
 
-    def parse_str(str)
-      raise ArgumentError, "not a valid string input" unless /^\s*[\d.]*\s*x\s*[\d.]*\s*$/.match?(str)
+# An immutable two dimensional vector.
+#
+# Coordinates are real numbers, and keep the type they were given.
+# Integer coordinates stay exact through arithmetic with integers, and
+# widen to floats when a float is involved.
+#
+#   Vector2d(2, 3) * 2   # => Vector2d(4,6)
+#   Vector2d(2, 3) * 0.5 # => Vector2d(1.0,1.5)
+#
+# Instances are frozen, so every operation returns a new vector instead
+# of changing the receiver. New vectors are built through #build, which
+# a subclass overrides to carry its own state across operations.
+#
+# .parse is the permissive constructor, and Vector2d() is shorthand for
+# it. .new takes exactly two coordinates.
+#
+#   Vector2d("2x3")    # => Vector2d(2,3)
+#   Vector2d.new(2, 3) # => Vector2d(2,3)
+#
+class Vector2d
+  extend Vector2d::Angles::ClassMethods
+  extend Vector2d::Constructors
+  extend Vector2d::Coordinates
+  extend Vector2d::Parsing
+  extend Vector2d::Projection::ClassMethods
+  include Vector2d::Angles
+  include Vector2d::Arithmetic
+  include Vector2d::Comparison
+  include Vector2d::Componentwise
+  include Vector2d::Conversions
+  include Vector2d::Coordinates
+  include Vector2d::Deprecation
+  include Vector2d::Dimensions
+  include Vector2d::Interpolation
+  include Vector2d::Lengths
+  include Vector2d::MatrixInterop
+  include Vector2d::Projection
 
-      x, y = str.split("x")
-      new(x.to_f, y.to_f)
-    end
+  # Builds a new vector of this class from two coordinates, the way
+  # .parse and .from_angle do. Override it in a subclass whose
+  # constructor requires more than the coordinates, and see #build for
+  # the instance side.
+  #
+  #   class Labeled < Vector2d
+  #     attr_reader :label
+  #
+  #     def initialize(x, y, label = nil)
+  #       @label = label
+  #       super(x, y)
+  #     end
+  #
+  #     def self.build(x, y) = new(x, y, "unlabeled")
+  #   end
+  #
+  #   Labeled.parse("2x3").label # => "unlabeled"
+  #
+  # @param x [Integer, Float, Rational, BigDecimal] the x coordinate
+  # @param y [Integer, Float, Rational, BigDecimal] the y coordinate
+  # @return [Vector2d] a vector of this class
+  def self.build(x, y)
+    new(x, y)
   end
 
+  # The coordinates.
+  #
+  #   Vector2d(2, 3).x # => 2
+  #   Vector2d(2, 3).y # => 3
+  #
+  # @return [Integer, Float, Rational, BigDecimal]
   attr_reader :x, :y
 
+  # Creates a vector from two coordinates, which must be real numbers.
+  # Every vector is constructed through here, so this is what keeps a
+  # coordinate from being anything else. Instances are frozen.
+  #
+  #   Vector2d.new(2, 3)                    # => Vector2d(2,3)
+  #   Vector2d.new(Complex(1, 2), 3)        # => ArgumentError
+  #   Vector2d.new(2, 3).frozen?            # => true
+  #   Ractor.shareable?(Vector2d.new(2, 3)) # => true
+  #
+  # @param x [Integer, Float, Rational, BigDecimal] the x coordinate
+  # @param y [Integer, Float, Rational, BigDecimal] the y coordinate
   def initialize(x, y)
-    @x = x
-    @y = y
+    @x = coordinate(x)
+    @y = coordinate(y)
+    freeze
+  end
+
+  # Copies are frozen too.
+  #
+  #   Vector2d(2, 3).dup.frozen? # => true
+  #
+  # @param other [Vector2d] the vector being copied
+  # @return [void]
+  def initialize_copy(other)
+    super
+    freeze
   end
 
   # Compares two vectors
   #
   #   Vector2d(2, 3) == Vector2d(2, 3) # => true
   #   Vector2d(2, 3) == Vector2d(1, 0) # => false
+  #   Vector2d(2, 3) == [2, 3]         # => false
   #
+  # @param other [Object] any object
+  # @return [Boolean]
   def ==(other)
-    other.x == x && other.y == y
+    other.is_a?(Vector2d) && other.x == x && other.y == y
+  end
+
+  # Compares two vectors for hash equality. Unlike #==, the other object
+  # must be a vector of the same class, and the coordinates must be of
+  # the same type.
+  #
+  #   Vector2d(2, 3).eql?(Vector2d(2, 3))     # => true
+  #   Vector2d(2, 3).eql?(Vector2d(2.0, 3.0)) # => false
+  #
+  # @param other [Object] any object
+  # @return [Boolean]
+  def eql?(other)
+    other.instance_of?(self.class) && x.eql?(other.x) && y.eql?(other.y)
+  end
+
+  # Hash value of the vector, consistent with #eql?.
+  #
+  #   Vector2d(2, 3).hash == Vector2d(2, 3).hash # => true
+  #
+  # @return [Integer]
+  def hash
+    [self.class, x, y].hash
+  end
+
+  # Builds a new vector of this class from two coordinates. Every method
+  # that returns a new vector goes through here, so a subclass whose
+  # constructor takes more than the coordinates only has to override
+  # this to have its own state carried across operations.
+  #
+  #   class Labeled < Vector2d
+  #     attr_reader :label
+  #
+  #     def initialize(x, y, label = nil)
+  #       @label = label
+  #       super(x, y)
+  #     end
+  #
+  #     def build(x, y) = self.class.new(x, y, label)
+  #   end
+  #
+  #   Labeled.new(2, 3, "point").abs.label # => "point"
+  #
+  # Class level constructors have no instance to carry state from, and
+  # use .build instead.
+  #
+  # @param x [Integer, Float, Rational, BigDecimal] the x coordinate
+  # @param y [Integer, Float, Rational, BigDecimal] the y coordinate
+  # @return [self]
+  def build(x, y)
+    self.class.build(x, y)
   end
 end
 
-# Instantiates a Vector2d
+# Shorthand for Vector2d.parse, and takes the same arguments.
 #
-#   Vector2d(2, 3) # => Vector2d(2,3)
+#   Vector2d(2, 3)    # => Vector2d(2,3)
+#   Vector2d("2x3")   # => Vector2d(2,3)
+#   Vector2d([2, 3])  # => Vector2d(2,3)
 #
+# @return [Vector2d]
+# @see Vector2d.parse for the arguments
 def Vector2d(*)
   Vector2d.parse(*)
 end