Class: Point3

Inherits:
Object show all
Defined in:
lib/point3.rb

Overview

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.

Constant Summary collapse

@@origin3 =

The 3D origin

Point3.new

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(x = 0, y = 0, z = 0) ⇒ Point3

Creates and returns a Point3 instance. Sets the coordinates values using the set method.



31
32
33
 
# File 'lib/point3.rb', line 31

def initialize(x=0, y=0, z=0)
  set x, y, z
end

Instance Attribute Details

#x ⇒ Object

x coordinate reader and writer.



18
19
20
 
# File 'lib/point3.rb', line 18

def x
  @x
end

#y ⇒ Object

y coordinate reader and writer.



20
21
22
 
# File 'lib/point3.rb', line 20

def y
  @y
end

#z ⇒ Object

z coordinate reader and writer.



22
23
24
 
# File 'lib/point3.rb', line 22

def z
  @z
end

Class Method Details

.origin ⇒ Object

Returns the origin of 3D space, where x, y, and z all have zero values.



25
26
27
 
# File 'lib/point3.rb', line 25

def Point3.origin
  @@origin3
end

Instance Method Details

#==(point3) ⇒ Object

Returns true if the coordinates of the instance are equal to the coordinates of the given point.



58
59
60
 
# File 'lib/point3.rb', line 58

def ==(point3)
  (@x == point3.x)&&(@y == point3.y)&&(@z == point3.z)
end

#add(x = 0, y = 0, z = 0) ⇒ Object Also known as: +

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.



147
148
149
 
# File 'lib/point3.rb', line 147

def add(x=0,y=0,z=0)
  point3.add!(x,y,z)
end

#add!(x = 0, y = 0, z = 0) ⇒ Object

Returns the modified instance with the arguments added.



154
155
156
157
158
159
160
161
162
 
# File 'lib/point3.rb', line 154

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

#approximately_equals?(point3, epsilon = Numeric.epsilon) ⇒ Boolean Also known as: =~

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.

Returns:

  • (Boolean) 


65
66
67
68
69
 
# File 'lib/point3.rb', line 65

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

#c_radius ⇒ Object

Returns the cylindrical radius coordinate of the instance.



99
100
101
 
# File 'lib/point3.rb', line 99

def c_radius   
  Math.sqrt((@x*@x)+(@y*@y))
end

#cross(x = 1/sqrt3, y = 1/sqrt3, z = 1/sqrt3) ⇒ Object

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.



246
247
248
 
# File 'lib/point3.rb', line 246

def cross(x=1/sqrt3,y=1/sqrt3,z=1/sqrt3)
  point3.cross!(x,y,z)
end

#cross!(x = 1/sqrt3, y = 1/sqrt3, z = 1/sqrt3) ⇒ Object

Returns the modified instance as the cross product.



251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/point3.rb', line 251

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

#distance_to(point3) ⇒ Object

Returns the 3D distance from the instance to point3.



115
116
117
 
# File 'lib/point3.rb', line 115

def distance_to(point3)
  Math.sqrt(((@x-point3.x)**2)+((@y-point3.y)**2)+((@z-point3.z)**2))
end

#dot(point3) ⇒ Object

Returns the dot product of the vectors represented by the instance and point3, with common endpoints at the origin.



126
127
128
 
# File 'lib/point3.rb', line 126

def dot(point3)
  (@x*point3.x)+(@y*point3.y)+(@z*point3.z)
end

#mirror ⇒ Object

Returns a new Point3 instance whose coordinates are the original instance’s mirrored through the origin.



132
133
134
 
# File 'lib/point3.rb', line 132

def mirror
  point3.mirror!
end

#mirror! ⇒ Object

Returns the modified instance whose coordinates have been mirrored through the origin.



138
139
140
 
# File 'lib/point3.rb', line 138

def mirror!
  set(-@x, -@y, -@z)
end

#modulus ⇒ Object

Returns the 3D distance from the instance to the origin.



120
121
122
 
# File 'lib/point3.rb', line 120

def modulus
  distance_to(origin)
end

#multiply(x = 1, y = 1, z = 1) ⇒ Object Also known as: *

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.



191
192
193
 
# File 'lib/point3.rb', line 191

def multiply(x=1,y=1,z=1)
  point3.multiply!(x,y,z)
end

#multiply!(x = 1, y = 1, z = 1) ⇒ Object

Returns the modified instance as multiplied by the arguments.



198
199
200
201
202
203
204
205
206
 
# File 'lib/point3.rb', line 198

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

#phi ⇒ Object

Returns the spherical phi coordinate of the instance.



109
110
111
112
 
# File 'lib/point3.rb', line 109

def phi
  m = modulus
  (m == 0)? 0 : Math.acos(z/m)
end

#point3(x = self.x, y = self.y, z = self.z) ⇒ Object

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.



77
78
79
 
# File 'lib/point3.rb', line 77

def point3(x=self.x,y=self.y,z=self.z)
  Point3.new(x,y,z)
end

#point3c(point3c = nil, point3 = self) ⇒ Object

Returns a 3D point in cylindrical coordinates, filling point3c if given, and copied from point3.



89
90
91
 
# File 'lib/point3.rb', line 89

def point3c(point3c=nil,point3=self)
  (point3c ||= Point3c.new).set(point3.c_radius,point3.theta,point3.z)
end

#point3s(point3s = nil, point3 = self) ⇒ Object

Returns a 3D point in spherical coordinates, filling point3s if given, and copied from point3.



83
84
85
 
# File 'lib/point3.rb', line 83

def point3s(point3s=nil,point3=self)
  (point3s ||= Point3s.new).set(point3.s_radius,point3.theta,point3.phi)
end

#s_radius ⇒ Object

Returns the spherical radius coordinate of the instance.



94
95
96
 
# File 'lib/point3.rb', line 94

def s_radius
  modulus
end

#scale(scalar = 1) ⇒ Object

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.



213
214
215
 
# File 'lib/point3.rb', line 213

def scale(scalar=1)
  point3.scale!(scalar)
end

#scale!(scalar = 1) ⇒ Object

Returns the modified instance as multiplied by the scalar.



218
219
220
221
222
223
224
225
226
 
# File 'lib/point3.rb', line 218

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

#set(x = 0, y = 0, z = 0) ⇒ Object

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.



45
46
47
48
49
50
51
52
53
54
 
# File 'lib/point3.rb', line 45

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

#subtract(x = 0, y = 0, z = 0) ⇒ Object Also known as: -

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.



169
170
171
 
# File 'lib/point3.rb', line 169

def subtract(x=0,y=0,z=0)
  point3.subtract!(x,y,z)
end

#subtract!(x = 0, y = 0, z = 0) ⇒ Object

Returns the modified instance with the arguments subtracted.



176
177
178
179
180
181
182
183
184
 
# File 'lib/point3.rb', line 176

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

#theta ⇒ Object

Returns the spherical/cylindrical theta coordinate of the instance.



104
105
106
 
# File 'lib/point3.rb', line 104

def theta
  (@x == 0)? ((@y > 0)? @@pio2 : -@@pio2) : Math.atan2(@y,@x)
end

#to_along(e, d, normalize = true) ⇒ Object

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.



268
269
270
271
 
# File 'lib/point3.rb', line 268

def to_along (e, d, normalize=true)
  scalar = normalize ? (distance_to e) : 1
  point3(e).subtract!(self).unit!.scale!(d*scalar).add(self)
end

#to_s ⇒ Object

Returns a string representation of the instance.



36
37
38
 
# File 'lib/point3.rb', line 36

def to_s
  "Point3: x #{x}  y #{y}  z #{z}"
end

#unit(x = 1, y = 1, z = 1) ⇒ Object

Returns a new Point3 instance representing the unit vector (with the same direction as the original instance, but whose length is 1.)



230
231
232
 
# File 'lib/point3.rb', line 230

def unit(x=1,y=1,z=1)
  point3.unit!
end

#unit!(x = 1, y = 1, z = 1) ⇒ Object

Returns the modified instance as the unit vector.



235
236
237
 
# File 'lib/point3.rb', line 235

def unit!(x=1,y=1,z=1)
  scale!(1/modulus)
end