eymiha_math3 0.1.0

data/gem_package.rb

@@ -0,0 +1,33 @@
+class GemPackage
+  
+  attr_reader :name, :version, :files
+  
+  def initialize
+    @name = 'eymiha_math3'
+    @version = '0.1.0'
+    @files = FileList[
+      '*.rb',
+      'lib/*',
+      'test/*',
+      'html/**/*'
+    ]
+  end
+
+  def fill_spec(s)
+    s.name = name
+    s.version = version
+    s.summary = "Emiyha - basic 3D math extensions"
+    s.files = files.to_a
+    s.require_path = 'lib'
+    s.autorequire = name
+    s.has_rdoc = true
+    s.rdoc_options << "--all"
+    s.author = "Dave Anderson"
+    s.email = "dave@eymiha.com"
+    s.homepage = "http://www.eymiha.com"
+    s.rubyforge_project = "cori"
+    s.add_dependency("eymiha",">= 0.1.0")
+    s.add_dependency("eymiha_math",">= 0.1.0")
+  end
+
+end

data/lib/envelope3.rb

@@ -0,0 +1,96 @@
+require 'eymiha_math3'
+require 'envelope'
+
+# 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
+
+  understands 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

data/lib/eymiha_math3.rb

@@ -0,0 +1,105 @@
+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 ThreeDimensions
+  
+  # shorthand for 2*pi.
+  def two_pi
+    2.0*Math::PI
+  end
+  
+  # shorthand for pi.
+  def pi
+    Math::PI
+  end
+  
+  # shorthand for pi.
+  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
+
+
+class Numeric
+  
+  understands 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
+
+
+require 'point3'
+require 'point3s'
+require 'point3c'
+require 'envelope3'
+require 'quaternion'

data/lib/point3.rb

@@ -0,0 +1,276 @@
+require 'eymiha_math3'
+
+# 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
+  
+  understands 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

data/lib/point3c.rb

@@ -0,0 +1,123 @@
+require 'eymiha_math3'
+
+# 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
+
+  understands 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