eymiha_math3 1.0.1 → 1.0.2

data/gem_package.rb

@@ -4,10 +4,10 @@ class GemPackage
   
   def initialize
     @name = 'eymiha_math3'
-    @version = '1.0.1'
+    @version = '1.0.2'
     @files = FileList[
       '*.rb',
-      'lib/*',
+      'lib/**/*',
       'test/*',
       'html/**/*'
     ]

data/lib/eymiha/math3.rb

@@ -0,0 +1,7 @@
+require 'eymiha/math3/math3'
+
+require 'eymiha/math3/envelope3'
+require 'eymiha/math3/point3'
+require 'eymiha/math3/point3c'
+require 'eymiha/math3/point3s'
+require 'eymiha/math3/quaternion'

data/lib/eymiha/math3/envelope3.rb

@@ -0,0 +1,100 @@
+require 'eymiha/math3'
+require 'eymiha/util/envelope'
+
+module Eymiha
+
+  # Envelope3 is the minimum 3D envelope that will completely contain a set of
+  # 3D points. 3D cartersian points or other 3D envelopes may be added to an
+  # instance, and it can return the number or points considered so far, the
+  # x, y and z envelopes, and the high and low Point3 boundaries.
+  class Envelope3 < BaseEnvelope
+    
+    include ThreeDimensions
+    
+    # 3D cartesian x coordinate envelope reader.
+    attr_reader :x
+    # 3D cartesian y coordinate envelope reader.
+    attr_reader :y
+    # 3D cartesian z coordinate envelope reader.
+    attr_reader :z
+    
+    # Creates and returns an instance. If arguments are given, they are passed to
+    # the set method to initialize the new instance.
+    def initialize(x=nil,y=0,z=0)
+      super()
+      @x = Envelope.new
+      @y = Envelope.new
+      @z = Envelope.new
+      add(x,y,z) unless x == nil
+    end
+    
+    # Returns a string representation of the instance.
+    def to_s
+      values = (count > 0)? "\n  high  #{high}\n  low   #{low}" : ""
+      "Envelope3: count #{count}#{values}"
+    end
+    
+    # Adds a value to the instance. When
+    # * x is an Envelope3, it is coalesced into the instance.
+    # * x responds like a Point3, its coordinates are added.
+    # * x us Numeric, the arguments are added.
+    # * otherwise, an EnvelopeException is raised.
+    # The modified instance is returned.
+    def add(x=0,y=0,z=0)
+      if x.kind_of? Envelope3
+        count = x.count
+        if count > 0
+          add x.high
+          add x.low
+          @count += (count-2)
+        end
+        self
+      elsif x.point3_like?
+        add x.x, x.y, x.z
+      elsif x.kind_of? Numeric
+        @x.add x
+        @y.add y
+        @z.add z
+        @count += 1
+        self
+      else
+        raise_no_compare x
+      end
+    end
+    
+    # Returns a Point3 whose coordinates are the high values of the x, y, and z
+    # envelopes.
+    # * if there are no boundaries, an EnvelopeException is raised.
+    def high
+      raise_no_envelope if @count == 0
+      (@high ||= Point3.new).set @x.high, @y.high, @z.high
+    end
+    
+    # Returns a Point3 whose coordinates are the low values of the x, y, and z
+    # envelopes.
+    # * if there are no boundaries, an EnvelopeException is raised.
+    def low
+      raise_no_envelope if @count == 0
+      (@low ||= Point3.new).set @x.low, @y.low, @z.low
+    end
+    
+    # Returns true if the instance completely contains the arguments:
+    # * x is an Envelope3, its high and low are contained.
+    # * x responds like a Point3, its coordinates are contained.
+    # * x is Numeric, the arguments are contained.
+    # * otherwise, false is returned.
+    def contains?(x=0,y=0,z=0)
+      if x.kind_of? Envelope3
+        (contains? x.high) && (contains? x.low)
+      elsif x.point3_like?
+        contains?(x.x,x.y,x.z)
+      elsif x.kind_of? Numeric
+        (@x.contains? x) && (@y.contains? y) && (@z.contains? z)
+      else
+        raise_no_compare x
+      end
+    end
+    
+  end
+  
+end

data/lib/eymiha/math3/math3.rb

@@ -0,0 +1,100 @@
+require 'eymiha'
+require 'eymiha/math'
+
+# These modifications to objects add 3D point duck classifying.
+class Object
+  
+  # Returns true if the instance has 3D cartesian coordinates, ie. responds 
+  # to x, y and z.
+  def point3_like?
+    (respond_to? :x)&&(respond_to? :y)&&(respond_to? :z)
+  end
+  
+  # Returns true if the instance has 3D spherical coordinates, ie. responds
+  # to s_radius, theta and phi.
+  def point3s_like?
+    (respond_to? :s_radius)&&(respond_to? :theta)&&(respond_to? :phi)
+  end
+  
+  # Returns true if the instance has 3D cylindrical coordinates, ie responds
+  # to c_radius, theta and z.
+  def point3c_like?
+    (respond_to? :c_radius)&&(respond_to? :theta)&&(respond_to? :z)
+  end
+
+end
+
+# The ThreeDimensions module adds shorthands for common 3D entities, mostly to
+# improve code readability.
+module Eymiha
+  module ThreeDimensions
+  
+    # shorthand for 2*pi.
+    def two_pi
+      2.0*Math::PI
+    end
+    
+    # shorthand for pi.
+    def pi
+      Math::PI
+    end
+    
+    # shorthand for pi/2.
+    def half_pi
+      Math::PI/2.0
+    end
+    
+    # shorthand for the square root of 2.
+    def sqrt2
+      Math.sqrt 2
+    end
+    
+    # shorthand for the square root of 3.
+    def sqrt3
+      Math.sqrt 3
+    end
+    
+    # the origin of 3D space.
+    def origin
+      Point3.origin
+    end
+    
+    # shorthand for creating a 3D point in cartesian coordinates.
+    def point3(x=0, y=0, z=0)
+      Point3.new(x,y,z)
+    end
+    
+    # shorthand for creating a 3D point in spherical coordinates.
+    def point3s(s_radius=0, theta=0, phi=0)
+      Point3s.new(s_radius,theta,phi)
+    end
+    
+    # shorthand for creating a 3D point in cylindrical coordinates.
+    def point3c(c_radius=0, theta=0, z=0)
+      Point3c.new(c_radius,theta,z)
+    end
+    
+    # shorthand for creating a quaternion.
+    def quaternion(axis=origin,real=0)
+      Quaternion.new(axis,real)
+    end
+    
+  end
+end
+
+
+class Numeric
+  
+  include Eymiha::ThreeDimensions
+  
+  # Returns the instance's value folded to lie between [0, 2*pi).
+  def rectify_theta
+    wrap_rectify two_pi
+  end
+  
+  # Returns the instance's value cut to lie between [0, pi].
+  def rectify_phi
+    cut_rectify pi
+  end
+  
+end

data/lib/eymiha/math3/point3.rb

@@ -0,0 +1,283 @@
+require 'eymiha/math3'
+
+module Eymiha
+
+  # Point3 represents a 3D point in cartesian coordinates:
+  # * x is the signed distance from the 3D origin along the x axis.
+  # * y is the signed distance from the 3D origin along the y axis.
+  # * z is the signed distance from the 3D origin along the z axis.
+  # The cylindrical z coordinate is equal to the cartesian z coordinate.
+  #
+  # Point3 instances may be converted to Point3s and Point3c instances, but
+  # information at the "boundaries" may be lost. Besides responding as a Point3,
+  # an instance will also respond like a Point3s and Point3c as it has a full 
+  # complement of readers for the different coordinate systems.
+  class Point3
+    
+    include ThreeDimensions
+    
+    # x coordinate reader and writer.
+    attr_accessor :x
+    # y coordinate reader and writer.
+    attr_accessor :y
+    # z coordinate reader and writer.
+    attr_accessor :z
+    
+    # Returns the origin of 3D space, where x, y, and z all have zero values.
+    def Point3.origin
+      @@origin3
+    end
+    
+    # Creates and returns a Point3 instance. Sets the coordinates values using
+    # the set method.
+    def initialize(x=0, y=0, z=0)
+      set x, y, z
+    end
+    
+    # Returns a string representation of the instance.
+    def to_s
+      "Point3: x #{x}  y #{y}  z #{z}"
+    end
+    
+    # Sets the coordinate values of the instance. When
+    # * x is Numeric, the arguments are interpretted as coordinates.
+    # * x responds like a Point3, its cartesian coordinates are assigned.
+    # * otherwise a TypeError is raised.
+    # The modified instance is returned.
+    def set(x=0, y=0, z=0)
+      if x.kind_of? Numeric
+        @x, @y, @z = 1.0*x, 1.0*y, 1.0*z
+      elsif x.point3_like?
+        set x.x, x.y, x.z
+      else
+        raise_no_conversion x
+      end
+      self
+    end
+    
+    # Returns true if the coordinates of the instance are equal to the
+    # coordinates of the given point.
+    def ==(point3)
+      (@x == point3.x)&&(@y == point3.y)&&(@z == point3.z)
+    end
+    
+    # Returns true if the coordinates of the instance are approximately equal
+    # to the coordinates of the given point, each coordinate less than a distance
+    # epsilon from the target.
+    def approximately_equals?(point3,epsilon=Numeric.epsilon)
+      @x.approximately_equals?(point3.x,epsilon)&&
+        @y.approximately_equals?(point3.y,epsilon)&&
+        @z.approximately_equals?(point3.z,epsilon)
+    end
+    
+    alias =~ approximately_equals?
+    
+    # Returns a copy of point3 with the given cartesian coordinates:
+    # * x is Numeric, the arguments are copied as the coordinates.
+    # * x responds like a Point3, its coordinates are copied.
+    # * otherwise a TypeError is raised.
+    def point3(x=self.x,y=self.y,z=self.z)
+      Point3.new(x,y,z)
+    end
+    
+    # Returns a 3D point in spherical coordinates, filling point3s if given,
+    # and copied from point3.
+    def point3s(point3s=nil,point3=self)
+      (point3s ||= Point3s.new).set(point3.s_radius,point3.theta,point3.phi)
+    end
+    
+    # Returns a 3D point in cylindrical coordinates, filling point3c if given,
+    # and copied from point3. 
+    def point3c(point3c=nil,point3=self)
+      (point3c ||= Point3c.new).set(point3.c_radius,point3.theta,point3.z)
+    end
+    
+    # Returns the spherical radius coordinate of the instance.
+    def s_radius
+      modulus
+    end
+    
+    # Returns the cylindrical radius coordinate of the instance.
+    def c_radius   
+      Math.sqrt((@x*@x)+(@y*@y))
+    end
+    
+    # Returns the spherical/cylindrical theta coordinate of the instance.
+    def theta
+      (@x == 0)? ((@y > 0)? @@pio2 : -@@pio2) : Math.atan2(@y,@x)
+    end
+    
+    # Returns the spherical phi coordinate of the instance.
+    def phi
+      m = modulus
+      (m == 0)? 0 : Math.acos(z/m)
+    end
+    
+    # Returns the 3D distance from the instance to point3.
+    def distance_to(point3)
+      Math.sqrt(((@x-point3.x)**2)+((@y-point3.y)**2)+((@z-point3.z)**2))
+    end
+    
+    # Returns the 3D distance from the instance to the origin.
+    def modulus
+      distance_to(origin)
+    end
+    
+    # Returns the dot product of the vectors represented by the instance and
+    # point3, with common endpoints at the origin.
+    def dot(point3)
+      (@x*point3.x)+(@y*point3.y)+(@z*point3.z)
+    end
+    
+    # Returns a new Point3 instance whose coordinates are the original
+    # instance's mirrored through the origin.
+    def mirror
+      point3.mirror!
+    end
+    
+    # Returns the modified instance whose coordinates have been mirrored through
+    # the origin.
+    def mirror!
+      set(-@x, -@y, -@z)
+    end
+    
+    # Returns a new Point3 instance whose coordinates are the original
+    # instance's with the given amounts added:
+    # * x is Numeric, the arguments are added to the coordinates.
+    # * x responds like a Point3, its cartesian coordinates are added.
+    # * otherwise a TypeError is raised.
+    def add(x=0,y=0,z=0)
+      point3.add!(x,y,z)
+    end
+    
+    alias + add
+    
+    # Returns the modified instance with the arguments added.
+    def add!(x=0,y=0,z=0)
+      if x.kind_of? Numeric
+        set(@x+x, @y+y, @z+z)
+      elsif x.point3_like?
+        add! x.x, x.y, x.z
+      else
+        raise_no_conversion x
+      end
+    end
+    
+    # Returns a new Point3 instance whose coordinates are the original
+    # instance's with the given amounts subtracted:
+    # * x is Numeric, the arguments are subtracted from the coordinates.
+    # * x responds like a Point3, its cartesian coordinates are subtracted.
+    # * otherwise a TypeError is raised.
+    def subtract(x=0,y=0,z=0)
+      point3.subtract!(x,y,z)
+    end
+    
+    alias - subtract
+    
+    # Returns the modified instance with the arguments subtracted.
+    def subtract!(x=0,y=0,z=0)
+      if x.kind_of? Numeric
+        add!(-x, -y, -z)
+      elsif x.point3_like?
+        subtract! x.x, x.y, x.z
+      else
+        raise_no_conversion x
+      end
+    end
+    
+    # Returns a new Point3 instance whose coordinates are the original
+    # instance's multiplied by the given amounts:
+    # * x is Numeric, the coordinates are multiplied by the arguments.
+    # * x responds like a Point3, the instance's coordinates are multiplied by x's coordinates.
+    # * otherwise a TypeError is raised.
+    def multiply(x=1,y=1,z=1)
+      point3.multiply!(x,y,z)
+    end
+    
+    alias * multiply
+    
+    # Returns the modified instance as multiplied by the arguments.
+    def multiply!(x=1,y=1,z=1)
+      if x.kind_of? Numeric
+        set(@x*x, @y*y, @z*z)
+      elsif x.point3_like?
+        multiply! x.x, x.y, x.z
+      else
+        raise_no_conversion x
+      end
+    end
+    
+    # Returns a new Point3 instance whose coordinates are the original
+    # instance's multiplied by the scalar.
+    # * scalar is Numeric, the arguments are multiplied by the coordinates.
+    # * x responds like a Point3, the instance is multiplied by the scalar.
+    # * otherwise a TypeError is raised.
+    def scale(scalar=1)
+      point3.scale!(scalar)
+    end
+    
+    # Returns the modified instance as multiplied by the scalar.
+    def scale!(scalar=1)
+      if scalar.kind_of? Numeric
+        multiply! scalar, scalar, scalar
+      elsif scalar.point3_like?
+        multiply! scalar
+      else
+        raise_no_conversion scalar
+      end
+    end
+    
+    # Returns a new Point3 instance representing the unit vector (with the same
+    # direction as the original instance, but whose length is 1.)
+    def unit(x=1,y=1,z=1)
+      point3.unit!
+    end
+    
+    # Returns the modified instance as the unit vector.
+    def unit!(x=1,y=1,z=1)
+      scale!(1/modulus)
+    end
+    
+    # Returns a new Point3 instance that is the cross product of the given
+    # arguments treated as vectors with endpoints at the origin:
+    # * x is Numeric, the cross product of the instance with the arguments.
+    # * x responds like a Point3,
+    #   * y is Numeric, the cross product of the instance with x's coordinates.
+    #   * y responds like a Point3, the cross product of x with y.
+    # * otherwise a TypeError is raised.
+    def cross(x=1/sqrt3,y=1/sqrt3,z=1/sqrt3)
+      point3.cross!(x,y,z)
+    end
+    
+    # Returns the modified instance as the cross product.
+    def cross!(x=1/sqrt3,y=1/sqrt3,z=1/sqrt3)
+      if x.kind_of? Numeric
+        set((@y*z)-(@z*y), (@z*x)-(@x*z), (@x*y)-(@y*x))
+      elsif x.point3_like?
+        if y.kind_of? Numeric
+          cross! x.x, x.y, x.z
+        elsif y.point3_like?
+          set(x).cross!(y)
+        else
+          raise_no_conversion y
+        end
+      else
+        raise_no_conversion x
+      end
+    end
+    
+    # Returns a new Point3 that is a distance d from the instance along the
+    # line to the Point3 e. If normalized is true, the d argument specifies
+    # the fraction of the distance from the instance (being 0) to e (being 1).
+    #If normalize is false, the d argument specifies an absolute distance.
+    def to_along (e, d, normalize=true)
+      scalar = normalize ? (distance_to e) : 1
+      point3(e).subtract!(self).unit!.scale!(d*scalar).add(self)
+    end
+    
+    # The 3D origin
+    @@origin3 = Point3.new
+    
+  end
+
+end

data/lib/eymiha/math3/point3c.rb

@@ -0,0 +1,127 @@
+require 'eymiha/math3'
+
+module Eymiha
+
+  # Point3c represents a 3D point in cylindrical coordinates:
+  # * c_radius is the distance from the cylindrical axis.
+  # * theta is the angular distance around the cylindrical axis.
+  # * z is the distance from the cylindrical base-plane.
+  # The cylindrical theta coordinate is equal to the spherical theta. The
+  # cylindrical z coordinate is equal to the cartesian z coordinate.
+  #
+  # 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 cylindrical plane is the plane z=0.
+  #
+  # Point3c instances may be converted to Point3 and Point3s instances, but
+  # information at the "boundaries" may be lost. Besides responding as a Point3c,
+  # an instance will also respond like a Point3 and Point3s as it has a full 
+  # complement of readers for the different coordinate systems.
+  class Point3c
+    
+    include ThreeDimensions
+    
+    # cylindrical radius coordinate reader and writer.
+    attr_accessor :c_radius
+    # cylindrical z coordinate reader and writer.
+    attr_accessor :z
+    # cylindrical theta reader.
+    attr_reader :theta
+    
+    # cylindrical theta coordinate writer, rectifying theta to a value in
+    # [0, 2*pi).
+    def theta=(theta)
+      @theta = theta.rectify_theta
+    end
+    
+    # Creates and returns a Point3c instance. Sets the coordinates values using
+    # the set method.
+    def initialize(c_radius=0, theta=0, z=0)
+      set c_radius, theta, z
+    end
+    
+    # Returns a string representation of the instance.
+    def to_s
+      "Point3c: c_radius #{c_radius}  theta #{theta}  z #{z}"
+    end
+    
+    # Sets the coordinate values of the instance. When
+    # * c_radius is Numeric, the arguments are interpretted as coordinates.
+    # * c_radius responds like a Point3c, its cylindrical coordinates are assigned.
+    # * otherwise a TypeError is raised.
+    # The modified instance is returned.
+    def set(c_radius=0, theta=0, z=0)
+      if c_radius.kind_of? Numeric
+        @c_radius, @theta, @z = 1.0*c_radius, (1.0*theta).rectify_theta, 1.0*z
+      elsif c_radius.point3c_like?
+        set c_radius.c_radius, c_radius.theta, c_radius.z
+      else
+        raise_no_conversion c_radius
+      end
+      self
+    end
+    
+    # Returns true if the coordinates of the instance are effectively equal to the
+    # coordinates of the given point.
+    def ==(point3c)
+      ((point3c.c_radius == c_radius) && (point3c.z == z)) &&
+        (((c_radius == 0) && (z == 0)) || (point3c.theta == theta))
+    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?(point3c,epsilon=Numeric.epsilon)
+      (@c_radius.approximately_equals?(point3c.c_radius,epsilon) &&
+       @z.approximately_equals?(point3c.z,epsilon)) &&
+        ((@c_radius.approximately_equals?(0,epsilon) &&
+          @z.approximately_equals?(0,epsilon)) ||
+         @theta.approximately_equals?(point3c.theta,epsilon))
+    end
+    
+    alias =~ approximately_equals?
+    
+    # Returns a 3D point in cartesian coordinates, filling point3 if given,
+    # and copied from point3c.
+    def point3(point3=nil,point3c=self)
+      (point3 ||= Point3.new).set(point3c.x,point3c.y,point3c.z)
+    end
+    
+    # Returns a 3D point in spherical coordinates, filling point3s if given,
+    # and copied from point3c.
+    def point3s(point3s=nil,point3c=self)
+      (point3s ||= Point3s.new).set(point3c.s_radius,point3c.theta,point3c.phi)
+    end
+    
+    # Returns a copy of point3c with the given cylindrical coordinates:
+    # * c_radius is Numeric, the arguments are copied as the coordinates.
+    # * c_radius responds like a Point3c, its coordinates are copied.
+    # * otherwise a TypeError is raised.
+    def point3c(c_radius=self.c_radius,theta=self.theta,z=self.z)
+      Point3c.new(c_radius,theta,z)
+    end
+    
+    # Returns the cartesian x coordinate of the instance.
+    def x
+      c_radius*Math.cos(theta)
+    end
+    
+    # Returns the cartesian y coordinate of the instance.
+    def y
+      c_radius*Math.sin(theta)
+    end
+    
+    # Returns the spherical radius coordinate of the instance.
+    def s_radius
+      Math.sqrt((x**2)+(y**2)+(z**2))
+    end
+    
+    # Returns the spherical phi coordinate of the instance.
+    def phi
+      m = s_radius
+      (m == 0)? 0 : Math.acos(z/m)
+    end
+    
+  end
+
+end

data/lib/eymiha/math3/point3s.rb

@@ -0,0 +1,132 @@
+require 'eymiha/math3'
+
+module Eymiha
+
+  # 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
+    
+    include 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
+
+end

data/lib/eymiha/math3/quaternion.rb

@@ -0,0 +1,246 @@
+require 'eymiha/math3'
+
+module Eymiha
+
+  # 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
+    
+    include 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
+  
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: eymiha_math3
 version: !ruby/object:Gem::Version 
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors: 
 - Dave Anderson
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-09-15 00:00:00 -04:00
+date: 2008-10-20 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -44,6 +44,14 @@ files:
 - gem_package.rb
 - rakefile.rb
 - lib/eymiha
+- lib/eymiha/math3
+- lib/eymiha/math3/envelope3.rb
+- lib/eymiha/math3/math3.rb
+- lib/eymiha/math3/point3.rb
+- lib/eymiha/math3/point3c.rb
+- lib/eymiha/math3/point3s.rb
+- lib/eymiha/math3/quaternion.rb
+- lib/eymiha/math3.rb
 - lib/eymiha_math3.rb
 - test/tc_envelope3.rb
 - test/tc_point3.rb