eymiha_math3 0.1.0

data/lib/point3s.rb

@@ -0,0 +1,128 @@
+require 'eymiha_math3'
+
+# Point3s represents a 3D point in spherical coordinates:
+# * s_radius is the distance from the origin.
+# * theta is the angular distance around the cylindrical axis.
+# * phi is angle that rotates the cylindrical axis to be directed at the point.
+# The spherical theta coordinate is equal to the cylindrical theta.
+#
+# From a cartesian reference, the cylindrical axis is the z axis, theta is
+# measured using the right hand rule with the positive x axis representing 0,
+# and the phi is an angle measured from the positive z axis.
+#
+# Point3s instances may be converted to Point3 and Point3c instances, but
+# information at the "boundaries" may be lost. Besides responding as a Point3s,
+# an instance will also respond like a Point3 and Point3c as it has a full 
+# complement of readers for the different coordinate systems.
+class Point3s
+
+  understands ThreeDimensions
+  
+  # spherical radius coordinate reader and writer.
+  attr_accessor :s_radius
+  # spherical theta coordinate reader.
+  attr_reader :theta
+  # spherical phi coordinate reader.
+  attr_reader :phi
+  
+  # spherical coordinate theta writer, rectifying theta to a value in
+  # [0, 2*pi).
+  def theta=(theta)
+    @theta = theta.rectify_theta
+  end
+  
+  # spherical coordinate theta writer, rectifying theta to a value in
+  # [0, pi].
+  def phi=(phi)
+    @phi = phi.rectify_phi
+  end
+
+  # Creates and returns a Point3s instance. Sets the coordinates values using
+  # the set method.
+  def initialize(s_radius=0, theta=0, phi=0)
+    set s_radius, theta, phi
+  end
+
+  # Returns a string representation of the instance.
+  def to_s
+    "Point3s: s_radius #{s_radius}  theta #{theta}  phi #{phi}"
+  end
+  
+  # Returns a string representation of the instance.
+  # Sets the coordinate values of the instance. When
+  # * s_radius is Numeric, the arguments are interpretted as coordinates.
+  # * s_radius responds like a Point3c, its spherical coordinates are assigned.
+  # * otherwise a TypeError is raised.
+  # The modified instance is returned.
+  def set(s_radius=0, theta=0, phi=0)
+    if s_radius.kind_of? Numeric
+      @s_radius, @theta, @phi =
+        1.0*s_radius, (1.0*theta).rectify_theta, (1.0*phi).rectify_phi
+    elsif s_radius.point3s_like?
+      set s_radius.s_radius, s_radius.theta, s_radius.phi
+    else
+      raise_no_conversion s_radius
+    end
+    self
+  end
+
+  # Returns true if the coordinates of the instance are effectively equal to the
+  # coordinates of the given point.
+  def ==(point3s)
+    (point3s.s_radius == s_radius) &&
+      ((s_radius == 0) || ((point3s.theta == theta) && (point3s.phi == phi)))
+  end
+
+  # Returns true if the coordinates of the instance are approximately
+  # effectively equal to the coordinates of the given point, each coordinate
+  # less than a distance epsilon from the target.
+  def approximately_equals?(point3s,epsilon=Numeric.epsilon)
+    (@s_radius.approximately_equals?(point3s.s_radius,epsilon)&&
+     ((@s_radius.approximately_equals?(0,epsilon) ||
+       (@theta.approximately_equals?(point3s.theta,epsilon)&&
+        @phi.approximately_equals?(point3s.phi,epsilon)))))
+  end
+
+  alias =~ approximately_equals?
+  
+  # Returns a 3D point in cartesian coordinates, filling point3 if given,
+  # and copied from point3s.
+  def point3(point3=nil, point3s=self)
+    (point3 ||= Point3.new).set(point3s.x,point3s.y,point3s.z)
+  end
+
+  # Returns a copy of point3s with the given spherical coordinates:
+  # * s_radius is Numeric, the arguments are copied as the coordinates.
+  # * s_radius responds like a Point3c, its coordinates are copied.
+  # * otherwise a TypeError is raised.
+  def point3s(s_radius=self.s_radius,theta=self.theta,phi=self.phi)
+    Point3s.new(s_radius,theta,phi)
+  end
+
+  # Returns a 3D point in cartesian coordinates, filling point3 if given,
+  # and copied from point3s.
+  def point3c(point3c=nil,point3s=self)
+    (point3c ||= Point3c.new).set(point3s.c_radius,point3s.theta,point3s.z)
+  end
+
+  # Returns the cartesian x coordinate of the instance.
+  def x
+    s_radius*Math.cos(theta)*Math.sin(phi)
+  end
+
+  # Returns the cartesian y coordinate of the instance.
+  def y
+    s_radius*Math.sin(theta)*Math.sin(phi)
+  end
+
+  # Returns the cartesian z coordinate of the instance.
+  def z
+    s_radius*Math.cos(phi);
+  end
+
+  # Returns the cylindrical radius coordinate of the instance.
+  def c_radius
+    s_radius*Math.sin(phi)
+  end
+  
+end

data/lib/quaternion.rb

@@ -0,0 +1,242 @@
+require 'eymiha_math3'
+
+# Quaternion instances represents Quaternions, complex numbers with one real
+# part and three imaginary parts. While the math is a bit obscure, they can be
+# used to manipulate 3D rotations without "gimbal lock", the problem of
+# coincident viewing angle alignment problems at the boundaries, for example,
+# where the difference between the x and y coordinates of the viewing vector
+# are zero (ie. looking straight up or straight down.)
+#
+# Interestingly, Quaternions were first conceptualized by Hamilton in 1843,
+# well before the widespread use of vector notation. While mostly put on the
+# shelf, they still solve certain problems elegantly, and in some cases more
+# quickly than matrix-based 3D calulations.
+#
+# The quaternion's real part is accessed through the real instance variable,
+# the three complex parts as the quaternion's "axis" vector, a Point3.
+class Quaternion
+  
+  understands ThreeDimensions
+
+  # complex axis vector part reader and writer
+  attr_accessor :axis
+  # real part reader and writer
+  attr_accessor :real
+  
+  # Creates and returns a Quaternion instance. Sets the coordinates values
+  # using the set method.
+  def initialize(axis=origin,real=0)
+    set axis, real
+  end
+
+  # Returns a string representation of the instance.
+  def to_s
+    "Quaternion:  axis: x #{axis.x}  y #{axis.y} z #{axis.z}   real #{real}"
+  end
+
+  # Sets the axis and real values of the instance. When
+  # * axis is a Quaternion, the arguments are interpretted as the parts of a quaternion.
+  # * axis reponds like a Point3, the axis and real are used to set the quaternion's values.
+  # * otherwise a TypeError is raised.
+  # The modified instance is returned.
+  def set(axis=origin,real=0)
+    if axis.kind_of? Quaternion
+      set axis.axis, axis.real
+    elsif axis.point3_like?
+      (@axis ||= point3).set(axis)
+      @real = real
+    else
+      raise_no_conversion(self.class.name,axis)
+    end
+    self
+  end
+  
+  # Returns true if the parts of the instance are equal to the
+  # parts of the given quaternion.
+  def ==(quaternion)
+    (@axis == quaternion.axis)&&(@real == quaternion.real)
+  end
+  
+  # Returns true if the parts of the instance are approximately
+  # equal to the parts of the given quaternion, each part
+  # less than a distance epsilon from the target.
+  def approximately_equals?(quaternion,epsilon=Numeric.epsilon)
+    (@axis.approximately_equals?(quaternion.axis,epsilon)&&
+     @real.approximately_equals?(quaternion.real,epsilon))
+  end
+
+  alias =~ approximately_equals?
+  
+  # Returns a copy of a Quaternion with the given parts:
+  # * axis is a Quaternion, its parts are copied.
+  # * axis responds like a Point3, the arguments are copied.
+  # * otherwise a TypeError is raised.
+  def quaternion(axis=self.axis,real=self.real)
+    Quaternion.new(axis,real)
+  end
+  
+  # Returns a new Quaternion-based encoding of a rotation.
+  def Quaternion.from_axis_angle(axis,angle)
+    half_angle = angle/2.0
+    Quaternion.new Point3.new(axis).scale(Math.sin(half_angle)),
+                   Math.cos(half_angle)
+  end
+  
+  # Returns a new Quaternion encoded into a rotation.
+  def to_axis_angle
+    half_angle = Math.acos(@real)
+    sin_half_angle = Math.sin(half_angle)
+    axis = (sin_half_angle.abs < 0.00000001)?
+      Point3.new(1,0,0) : Point3.new(@axis).scale!(1.0/sin_half_angle)
+    Quaternion.new(axis,2.0*half_angle)
+  end
+  
+  # Returns a new Quaternion instance whose parts are the original
+  # instance's with the given amounts added:
+  # * axis is a Quaternion, its parts are added.
+  # * axis responds like a Point3, the arguments are added.
+  # * otherwise a TypeError is raised.
+  def add(axis=origin,real=0)
+    quaternion.add!(axis,real)
+  end
+  
+  alias + add
+  
+  # Returns the modified instance with the arguments added.
+  def add!(axis=origin,real=0)
+    if axis.kind_of? Quaternion
+      add!(axis.axis,axis.real)
+    elsif axis.point3_like?
+      set(@axis+axis,@real+real)
+    else
+      raise_no_conversion axis
+    end
+    self
+  end
+  
+  # Returns a new Quaternion instance whose parts are the original
+  # instance's with the given amounts subtracted:
+  # * axis is a Quaternion, its parts are subtracted.
+  # * axis responds like a Point3, the arguments are subtracted.
+  # * otherwise a TypeError is raised.
+  def subtract(axis=origin,real=0)
+    quaternion.subtract!(axis,real)
+  end
+  
+  alias - subtract
+  
+  # Returns the modified instance with the arguments subtracted.
+  def subtract!(axis=origin,real=0)
+    if axis.kind_of? Quaternion
+      subtract!(axis.axis,axis.real)
+    elsif axis.point3_like?
+      set(@axis-axis,@real-real)
+    else
+      raise_no_conversion axis
+    end
+    self
+  end
+  
+  # Returns a new Quaternion instance whose parts are the original
+  # instance's multiplied by the given amounts:
+  # * axis is a Quaternion, the instance is multiplied by the axis' parts.
+  # * axis responds like a Point3, the instance is multiplied by the arguments.
+  # * otherwise a TypeError is raised.
+  def multiply(axis=origin,real=1)
+    quaternion.multiply!(axis,real)
+  end
+  
+  alias * multiply
+  
+  # Returns the modified instance multiplied by the arguments.
+  def multiply!(axis=origin,real=1)
+    if axis.kind_of? Quaternion
+      multiply!(axis.axis,axis.real)
+    elsif axis.point3_like?
+      r = (@real*real)-@axis.dot(axis)
+      p3 = axis.scale r
+      qp3 = @axis.scale real
+      cross = @axis.cross axis
+      a = p3.add!(qp3).add!(cross)
+      set(a,r)
+    else
+      raise_no_conversion axis
+    end
+    self
+  end
+  
+  # Returns a new Quaternion instance whose parts are the original
+  # instance's multiplied by the scalar:
+  # * scalar is a Quaternion, the instance is multiplied by the scalar's parts.
+  # * axis is a Numeric, the instance's parts are multiplied by the scalar.
+  # * otherwise a TypeError is raised.
+  def scale(scalar=1)
+    quaternion.scale!(scalar)
+  end
+  
+  # Returns the modified instance multiplied by the scalar.
+  def scale!(scalar=1)
+    if (scalar.kind_of? Quaternion)
+      multiply!(scalar)
+    elsif (scalar.kind_of? Numeric)
+      set(@axis.scale(scalar),@real*scalar)
+    else
+      raise_no_conversion scalar, "Numeric"
+    end
+  end
+  
+  # Returns a new Quaternion instance that is the conjugate of the original
+  # instance.
+  def conjugate
+    quaternion.conjugate!
+  end
+  
+  # Returns the modified instance replaced with its conjugate.
+  def conjugate!
+    set(@axis.mirror,@real)
+  end
+  
+  # Returns the norm of the instance.
+  def norm
+    (@real * @real) + @axis.modulus
+  end
+  
+  # Returns the absolute value of the instance.
+  def abs
+    Math.sqrt(norm)
+  end
+
+  # Returns a new Quaternion instance that is the inverse of the original
+  # instance.
+  def inverse
+    quaternion.inverse!
+  end
+  
+  # Returns the modified instance replaced with its inverse.
+  def inverse!
+    conjugate!
+    scale!(1.0/norm)
+  end
+  
+  # Returns a new Quaternion instance whose parts are the original
+  # instance's divided by the given amounts:
+  # * axis is a Quaternion, the instance is divided by the axis' parts.
+  # * axis responds like a Point3, the instance is divided by the arguments.
+  # * otherwise a TypeError is raised.
+  def divide(axis=origin,real=1)
+    quaternion.divide!(axis,origin)
+  end
+  
+  # Returns the modified instance divided by the arguments.
+  def divide!(axis=origin,real=1)
+    if axis.kind_of? Quaternion
+      divide!(axis.axis,axis.real)
+    elsif axis.point3_like?
+      multiply!(quaternion(axis,real).inverse!)
+    else
+      raise_no_conversion axis
+    end
+    self
+  end
+  
+end

data/rakefile.rb

@@ -0,0 +1,2 @@
+require 'gem_package'
+require 'gem_raker'

data/test/tc_envelope3.rb

@@ -0,0 +1,70 @@
+require 'test/unit'
+
+require 'envelope3'
+
+class TC_Envelope3 < Test::Unit::TestCase
+  
+  understands ThreeDimensions
+  
+  def test_empty
+    envelope3 = Envelope3.new
+    assert(envelope3.count == 0)
+    assert_raise(EnvelopeException) { envelope3.high }
+    assert_raise(EnvelopeException) { envelope3.low }
+  end
+  
+  def test_add
+    envelope3 = Envelope3.new
+    p3 = point3 1,2,3
+    envelope3.add p3
+    assert(envelope3.high == p3)
+    assert(envelope3.low == p3)
+    envelope3.add 2,4,6
+    assert(envelope3.high == point3(2,4,6))
+    assert(envelope3.low == point3(1,2,3))
+    assert(envelope3.count == 2)
+    envelope3.add point3(-3,5,-7)
+    envelope3.add point3(4.5,-3,1)
+    assert(envelope3.high == point3(4.5,5,6))
+    assert(envelope3.low == point3(-3,-3,-7))
+    assert(envelope3.count == 4)
+    envelope3.add envelope3
+    assert(envelope3.high == point3(4.5,5,6))
+    assert(envelope3.low == point3(-3,-3,-7))
+    assert(envelope3.count == 8)
+    assert_raise(EnvelopeException) { envelope3.add "bad" }
+    assert(envelope3.count == 8)
+  end
+
+  def test_contains
+    envelope3 = Envelope3.new(1,2,3).add(3,4,5)
+    assert(envelope3.contains?(1,2,3))
+    assert(envelope3.contains?(3,4,5))
+    assert(envelope3.contains?(2,3,4))
+    assert(!(envelope3.contains?(0,3,4)))
+    assert(!(envelope3.contains?(4,3,4)))
+    assert(!(envelope3.contains?(2,1,4)))
+    assert(!(envelope3.contains?(2,5,4)))
+    assert(!(envelope3.contains?(2,3,2)))
+    assert(!(envelope3.contains?(2,3,6)))
+    assert(envelope3.contains?(point3(1,2,3)))
+    assert(envelope3.contains?(point3(3,4,5)))
+    assert(envelope3.contains?(point3(2,3,4)))
+    assert(!(envelope3.contains?(point3(0,3,4))))
+    assert(!(envelope3.contains?(point3(4,3,4))))
+    assert(!(envelope3.contains?(point3(2,1,4))))
+    assert(!(envelope3.contains?(point3(2,5,4))))
+    assert(!(envelope3.contains?(point3(2,3,2))))
+    assert(!(envelope3.contains?(point3(2,3,6))))
+    assert(envelope3.contains?(envelope3))
+    assert(envelope3.contains?(Envelope3.new(1.5,2.5,3.5).add(2.5,3.5,4.5)))
+    assert(!(envelope3.contains? Envelope3.new(0.5,2.5,3.5).add(2.5,3.5,4.5)))
+    assert(!(envelope3.contains? Envelope3.new(1.5,1.5,3.5).add(2.5,3.5,4.5)))
+    assert(!(envelope3.contains? Envelope3.new(1.5,2.5,2.5).add(2.5,3.5,4.5)))
+    assert(!(envelope3.contains? Envelope3.new(1.5,2.5,3.5).add(3.5,3.5,4.5)))
+    assert(!(envelope3.contains? Envelope3.new(1.5,2.5,3.5).add(2.5,4.5,4.5)))
+    assert(!(envelope3.contains? Envelope3.new(1.5,2.5,3.5).add(2.5,3.5,5.5)))
+    assert_raise(EnvelopeException) { envelope3.contains? "bad" }
+  end
+
+end

data/test/tc_point3.rb

@@ -0,0 +1,221 @@
+require 'test/unit'
+
+require 'point3'
+
+class TC_Point3 < Test::Unit::TestCase
+  
+  understands ThreeDimensions
+  
+  def test_initialize_and_equality
+    p3 = Point3.new
+    assert(p3 == origin)
+    p3 = Point3.new 1,2,3
+    assert((p3.x == 1)&&(p3.y == 2)&&(p3.z == 3))
+    p3a = Point3.new 1,2,3
+    assert(p3 == p3a)
+    p3a = Point3.new 3,2,1
+    assert(p3 != p3a)
+  end
+  
+  def test_Object_point3
+    p3 = point3
+    assert(p3 == origin)
+    p3 = point3 1,2,3
+    assert((p3.x == 1)&&(p3.y == 2)&&(p3.z == 3))
+    p3a = Point3.new 1,2,3
+    assert((p3a.x == 1)&&(p3a.y == 2)&&(p3a.z == 3))
+    assert(p3 == p3a)
+  end
+  
+  def test_accessors
+    p3 = point3
+    assert(p3.point3_like?)
+    assert((p3.x == 0)&&(p3.y == 0)&&(p3.z == 0))
+    p3.x = 1
+    p3.y = 2
+    p3.z = 3
+    assert((p3.x == 1)&&(p3.y == 2)&&(p3.z == 3))
+    p3.x, p3.y, p3.z = 2, 4, 6
+    assert((p3.x == 2)&&(p3.y == 4)&&(p3.z == 6))
+  end
+  
+  def test_origin
+    p3 = origin
+    assert((p3.x == 0)&&(p3.y == 0)&&(p3.z == 0))
+  end
+  
+  def test_set
+    p3 = point3
+    p3.set 1, 2, 3
+    assert((p3.x == 1)&&(p3.y == 2)&&(p3.z == 3))
+    p3a = point3 p3
+    assert((p3a.x == 1)&&(p3a.y == 2)&&(p3a.z == 3))
+    p3b = point3
+    assert_raise(TypeError) { p3b.set "bad" }
+    assert_raise(TypeError) { point3 "bad" }
+  end
+
+  def test_copy
+    p3 = point3 1, 2, 3
+    p3a = p3.point3
+    assert(p3 == p3a)
+  end
+  
+  def test_spherical_and_cylindrical
+    p3 = point3 1, 2, 3
+    assert(p3.s_radius =~ 3.74165738677394)
+    assert(p3.c_radius =~ 2.23606797749979)
+    assert(p3.theta =~ 1.10714871779409)
+    assert(p3.phi =~ 0.640522312679425)
+  end
+  
+  def test_distance_to
+    p3a = point3 1, 2, 3
+    p3b = point3 5, -3, 4
+    assert(p3a.distance_to(p3b) =~ 6.48074069840786)
+  end
+  
+  def test_modulus
+    p3 = point3
+    assert(p3.modulus == 0)
+    p3.set 1, 2, 3
+    assert(p3.modulus =~ 3.74165738677394)
+  end
+  
+  def test_dot
+    p3a = point3 1, 2, 3
+    p3b = point3 5, -3, 4
+    assert(p3a.dot(p3b) =~ 11)
+  end
+  
+  def test_mirrors
+    p3a = point3 1, 2, 3
+    p3b = point3(-1, -2, -3)
+    assert(p3a.mirror == p3b)
+    p3a.mirror!
+    assert(p3a == p3b)
+  end
+
+  def test_adds
+    p3a = point3 1, 2, 3
+    p3d = point3 p3a
+    assert(p3a.add == p3d)
+    p3a.add!
+    assert(p3a == p3d)
+    p3b = point3 5, -3, 4
+    p3c = point3 6, -1, 7
+    assert(p3a.add(p3b) == p3c)
+    assert(p3a.add(p3b.x,p3b.y,p3b.z) == p3c)
+    assert(p3a+p3b == p3c)
+    p3a.add! p3b
+    assert(p3a == p3c)
+    p3d.add!(p3b.x,p3b.y,p3b.z)
+    assert(p3d == p3c)
+  end
+
+  def test_subtracts
+    p3a = point3 1, 2, 3
+    p3d = point3 p3a
+    assert(p3a.subtract == p3d)
+    p3a.subtract!
+    assert(p3a == p3d)
+    p3b = point3 5, -3, 4
+    p3c = point3(-4, 5, -1)
+    assert(p3a.subtract(p3b) == p3c)
+    assert(p3a.subtract(p3b.x,p3b.y,p3b.z) == p3c)
+    assert(p3a-p3b == p3c)
+    p3a.subtract! p3b
+    assert(p3a == p3c)
+    p3d.subtract!(p3b.x,p3b.y,p3b.z)
+    assert(p3d == p3c)
+  end
+
+  def test_multiplies
+    p3a = point3 1, 2, 3
+    p3d = point3 p3a
+    assert(p3a.multiply == p3d)
+    p3a.multiply!
+    assert(p3a == p3d)
+    p3b = point3 5, -3, 4
+    p3c = point3 5, -6, 12
+    assert(p3a.multiply(p3b) == p3c)
+    assert(p3a.multiply(p3b.x,p3b.y,p3b.z) == p3c)
+    assert(p3a*p3b == p3c)
+    p3a.multiply! p3b
+    assert(p3a == p3c)
+    p3d.multiply!(p3b.x,p3b.y,p3b.z)
+    assert(p3d == p3c)
+  end
+  
+  def test_scales
+    p3a = point3 1, 2, 3
+    p3d = point3 p3a
+    assert(p3a.scale == p3d)
+    p3a.scale!
+    assert(p3a == p3d)
+    p3b = point3 3, 6, 9
+    p3c = point3 3, 12, 27
+    assert(p3a.scale(3) == p3b)
+    assert(p3a.scale(p3b) == p3c)
+    p3a.scale! 3
+    assert(p3a == p3b)
+    p3d.scale! p3b
+    assert(p3d == p3c)
+  end
+  
+  def test_units_and_approximately_equals
+    p3a = point3 1, 2, 3
+    p3b = point3 0.267261241912424, 0.534522483824849, 0.801783725737273
+    assert(p3a.unit =~ p3b)
+    p3a.unit!
+    assert(p3a =~ p3b)
+    p3a = point3 1, 2, 3
+    p3b = point3 0.2672, 0.5345, 0.8017
+    assert(p3a.unit.approximately_equals?(p3b,0.0001))
+    p3a.unit!
+    assert(p3a.approximately_equals?(p3b,0.0001))
+  end
+
+  def test_cross
+    p3a = point3 1, 2, 3
+    p3b = point3 2, 4, 6
+    assert(p3a.cross(p3b) == origin)
+    p3b.cross! p3a
+    assert(p3b == origin)
+    p3c = point3 3, 2, 1
+    p3d = point3(-4, 8, -4)
+    assert(p3a.cross(p3c) == p3d)
+    p3a.cross! p3c
+    assert(p3a == p3d)
+  end
+  
+  def test_to_along
+    p3a = point3 1, 2, 3
+    p3b = point3(-10, 3, 4)
+    p3c = p3a.to_along p3b, 0
+    assert(p3c =~ p3a)
+    p3c = p3a.to_along p3b, 1
+    assert(p3c =~ p3b)
+  end
+  
+  def test_point3s
+    p3a = point3 1, 2, 3
+    p3s = p3a.point3s
+    assert(p3s.s_radius =~ 3.74165738677394)
+    assert(p3s.theta =~ 1.10714871779409)
+    assert(p3s.phi =~ 0.640522312679425)
+    p3b = p3s.point3
+    assert(p3a =~ p3b)
+  end
+
+  def test_point3c
+    p3a = point3 1, 2, 3
+    p3c = p3a.point3c
+    assert(p3c.c_radius =~ 2.23606797749979)
+    assert(p3c.theta =~ 1.10714871779409)
+    assert(p3c.z =~ 3)
+    p3b = p3c.point3
+    assert(p3a =~ p3b)
+  end
+
+end