class Vector3d

 

Parent: Object

Class Index

Methods: linear_combination, new, %, *, +, -, ==, [], []=, angle_between, axes, clone, cross, dot, inspect, length, length=, normalize, normalize!, parallel?, perpendicular?, reverse, reverse!, samedirection?, set!, to_a, to_s, transform, transform!, unitvector?, valid?, x, x=, y, y=, z, z=

 

Sample Code: vector3dtests.rb

 

The Vector3d class is used to manipulate vectors in a 3 dimensional space. 3d Vectors are essentially that combination of 3 numbers allowing you to find points in line in 3d space. For example a vector of 3,2,1 in 3d space suggests you have to go 3 points in the x direction, 2 points in the y direction, and 1 point in the z direction to find points from other points along the same line.
 

Class Methods


 

linear_combination

The linear_combination method is used to create a new vector as a linear combination of other vectors. This method is generally used to get a vector at some percentage between two vectors.

Syntax:

vector = Geom::Vector3d.linear_combination(weight1, vector1, weight2, vector2)

vector = Geom::Vector3d.linear_combination(x, xaxis, y, yaxis, z, zaxis)

Arguments:

weight1 - a weight or percentage

vector1 - the first vector

weight2 - a weight or percentage

vector2 - the end point of the line

Return Value:

vector - a Vector3d object

Comments:

A linear combination is a standard term for vector math. It is defined as point = weight1 * point1 + weight2 * point2.

Example:

vector1 = Geom::Vector3d.new 1,0,0
vector2 = Geom::Vector3d.new 0,1,0

# Gets the vector that is
# 3/4 the way from vector1 to vector2.
vector = Geom::Vector3d.linear_combination 0.25, vector1, 0.75, vector2
if (vector)
  UI.messagebox vector
else
  UI.messagebox "Failure"
end

 
 

new

The new method is used to create a new vector.

Syntax:

vector = Geom::Vector3d.new

vector = Geom::Vector3d.new(x, y, z)

vector = Geom::Vector3d.new(vector2)

Arguments:

x - a X value

y - a Y value

z - a Z value

vector2 - a Vector3d object

Return Value:

vector - a vector3d object

Comments:

 

Example:

# A vector that runs up the Z axis (that's the normal). The plane
# is perpendicular to the normal
vector = Geom::Vector3d.new 0,0,1
if (vector)
   UI.messagebox vector
else
   UI.messagebox "Failure"
end

 
 

Instance Methods

 

%

The % method is used to compute the dot product between two vectors.

Syntax:

d = vector1 % vector2

Arguments:

vector1 - a Vector3d object

vector 2 - a Vector3d object

Return Value:

d - the dot product if successful

Comments:

Values range from 1 to -1. If the two input vectors are pointing in the same direction, then the return value will be 1. If the two input vectors are pointing in opposite directions, then the return value will be -1. If the two input vectors are at right angles, then the return value will be 0. So, in effect, it is telling you how similar the two vectors are.

Example:

# A vector that runs up the Z axis (that's the normal). The plane
# is perpendicular to the normal
vector = Geom::Vector3d.new 0,0,1
vector2 = Geom::Vector3d.new 0,1,0
# Returns 0 which means the vectors are at a right angle to each other
d = vector % vector2
if (d)
   UI.messagebox d
else
   UI.messagebox "Failure"
end

 
 

*

The * method is used to compute the cross product between two vectors.

Syntax:

vector = vector1 * vector2

Arguments:

vector1 - a Vector3d object

vector2 - a Vector3d object

Return Value:

vector - a Vector3d object if successful

Comments:

The cross product, also called the vector product, is an operation on two vectors. The cross product of two vectors produces a third vector which is perpendicular to the plane in which the first two lie.

Example:

vector = Geom::Vector3d.new 1,0,0
vector2 = Geom::Vector3d.new 0,1,0

# A vector that runs up the Z axis (that's the normal). The plane
# is perpendicular to the normal
# Returns a vector that is perpendicular to the plane in which the first two vectors lie
# In this case, the new vector should be in the 0,0,1
v = vector * vector2
if (v)
   UI.messagebox v
else
   UI.messagebox "Failure"
end

 
 

+

The + method is used to add two vectors.

Syntax:

vector = vector1 + vector2

Arguments:

vector1 - a Vector3d object

vector2 - a Vector3d object

Return Value:

vector - a Vector3d object if successful

Comments:

 

Example:

vector = Geom::Vector3d.new 1,0,0
vector2 = Geom::Vector3d.new 0,1,0
# Returns a vector of 1,1,0
v = vector + vector2
if (v)
   UI.messagebox v
else
   UI.messagebox "Failure"
end

 
 

-

The - method is used to subtract two vectors.

Syntax:

vector = vector1 - vector2

Arguments:

vector1 - a Vector3d object

vector2 - a Vector3d object

Return Value:

vector - a Vector3d object if successful

Comments:

 

Example:

vector = Geom::Vector3d.new 1,0,0
vector2 = Geom::Vector3d.new 0,1,0
# Returns a vector of 1, -1, 0
v = vector - vector2
if (v)
   UI.messagebox v
else
   UI.messagebox "Failure"
end

 
 

==

The == method is used to determine if two vectors are equal to within tolerance.

Syntax:

status = vector1 == vector2

Arguments:

vector1 - a Vector3d object

vector2 - a Vector3d object

Return Value:

status - true if vector1 is equal to vector 2. False if they are not equal.

Comments:

 

Example:

vector = Geom::Vector3d.new 1,0,0
vector2 = Geom::Vector3d.new 0,1,0
status = vector == vector2
# Returns false
UI.messagebox status

 
 

[]

The [] method is used to access the coordinates of a vector as if it was an Array. The value of i must be 0, 1 or 2.

Syntax:

coordinate = vector[i]

Arguments:

i - an index into an array of three coordinates.

Return Value:

coordinate - the value for the x, y, or z coordinate.

Comments:

The following are equivalent:

x = vector.x

x = vector[0]

Example:

vector = Geom::Vector3d.new 1,0,0
value = vector[0]
if (value)
   UI.messagebox value
else
   UI.messagebox "Failure"
end

 
 

[]=

The []= method is used to set the coordinates of a vector as if it was an Array. The value of i must be 0, 1 or 2.

Syntax:

value = vector[i] = coordinate

Arguments:

coordinate - the value for the x, y, or z coordinate.

Return Value:

value - the newly set coordinate value

Comments:

 

Example:

vector = Geom::Vector3d.new 1,0,0
value = vector[0]
UI.messagebox value
newvalue = vector[0] = 2
if (newvalue)
   UI.messagebox newvalue
else
   UI.messagebox "Failure"
end

 
 

angle_between

The angle_between method is used to compute the angle (in radians) between this vector and another vector.

Syntax:

angle = vector.angle_between vector2

Arguments:

vector2 - a Vector3d object

Return Value:

angle - an angle (in radians)

Comments:

 

Example:

vector = Geom::Vector3d.new 1,0,0
vector2 = Geom::Vector3d.new 0,1,0
status = vector == vector2
angle = vector.angle_between vector2

 
 

axes

The axes method is used to compute an arbitrary set of axes with the given vector as the z-axis direction.

Syntax:

a = vector.axes

Arguments:

 

Return Value:

a - an Array object containing three Vector3d objects

Comments:

Returns an Array of three vectors [xaxis, yaxis, zaxis]

Example:

vector = Geom::Vector3d.new 1,0,0
a = vector.axes

 
 

clone

The clone method is used to make a copy of a vector.

Syntax:

vector2 = vector.clone

Arguments:

 

Return Value:

vector2 - a Vector3d object which is the clone of vector

Comments:

This method is equivalent to vec2 = Geom::Vector3d.new(vec)

Example:

vector = Geom::Vector3d.new 1,0,0
vector2 = vector.clone

 
 

cross

The cross method is used to compute the cross product between two vectors.

Syntax:

vector = vector1.cross vector2

Arguments:

vector2 - a Vector3d object

Return Value:

vector - the cross of vector1 and vector2

Comments:

 

Example:

vector = Geom::Vector3d.new 1,0,0
vector2 = Geom::Vector3d.new 0,1,0
v = vector.cross vector2


 

dot

The dot method is used to compute the dot product between two vectors.

Syntax:

d = vector1.dot vector2

Arguments:

vector2 - a Vector3d object

Return Value:

d - the dot product of vector1 and vector2

Comments:

 

Example:

vector = Geom::Vector3d.new 0,0,1
vector2 = Geom::Vector3d.new 0,1,0
d = vector.dot vector2

 
 

inspect

The inspect method is used to inspect the contents of a vector.

Syntax:

vector = vector.inspect

Arguments:

 

Return Value:

vector - the Vector3d object

Comments:

 

Example:

vector = Geom::Vector3d.new 0,0,1
v = vector.inspect

 
 

length

The length method is used to retrieve the length of the vector.

Syntax:

length = vector.length

Arguments:

 

Return Value:

length - the length of the vector

Comments:

 

Example:

vector = Geom::Vector3d.new 0,0,1
l = vector.length

 
 

length=

The length= method is used to set the length of the vector. The length must be greater than 0.

Syntax:

length = vector.length = length

Arguments:

length - a length for the vector

Return Value:

length - a newly set length

Comments:

 

Example:

vector = Geom::Vector3d.new 0,0,1
l = vector.length
UI.messagebox l
newl = vector.length = 2

 
 

normalize

The normalize method is used to retrieve a unit vector in the same direction as this vector.

Syntax:

vector2 = vector.normalize

Arguments:

 

Return Value:

vector2 - a normalized Vector3d object

Comments:

 

Example:

vector = Geom::Vector3d.new 0,0,1
vector2 = vector.normalize

 
 

normalize!

The normalize! method is used to convert a vector into a unit vector. Another way to do this is vec.length = 1

Syntax:

vector2 - vector.normalize!

Arguments:

 

Return Value:

vector2 - a normalized Vector3d object

Comments:

 

Example:

vector = Geom::Vector3d.new 0,0,1
vector2 = vector.normalize!

 
 

parallel?

The parallel method is used to determine if this vector is parallel to another vector to within tolerance.

Syntax:

status = vector.parallel? vector2

Arguments:

vector2 - a Vector3d object

Return Value:

status - true if vector and vector2 are parallel. False if they are not parallel.

Comments:

 

Example:

vector = Geom::Vector3d.new 0,0,1
vector2 = Geom::Vector3d.new 0,1,0
status = vector.parallel? vector2

 
 

perpendicular?

The perpendicular? method is used to determine if this vector is perpendicular to another vector to within tolerance.

Syntax:

status = vector.perpendicular? vector2

Arguments:

vector2 - a Vector3d object

Return Value:

status - true if vector and vector2 are parallel. False if they are not parallel.

Comments:

 

Example:

vector = Geom::Vector3d.new 0,0,1
vector2 = Geom::Vector3d.new 0,1,0
status = vector.perpendicular? vector2

 
 

reverse

The reverse method is used to retrieve a new vector that is the reverse of this vector.

Syntax:

vector2 = vector.reverse

Arguments:

 

Return Value:

vector2 - a Vector3d object that is the reverse of vector

Comments:

 

Example:

vector = Geom::Vector3d.new 0,0,1
vector2 = vector.reverse

 
 

reverse!

The reverse! method is used to retrieve the reverse the vector.

Syntax:

vector2 = vector.reverse!

Arguments:

 

Return Value:

vector2 - a Vector3d object that is the reverse of vector

Comments:

 

Example:

vector = Geom::Vector3d.new 0,0,1
vector2 = vector.reverse!

 
 

samedirection?

The samedirection? method is used to determine if this vector is parallel to and in the same direction as another vector to within tolerance.

Syntax:

status = vector.same_direction? vector2

Arguments:

vector2 - a Vector3D object

Return Value:

status - true if vector and vector2 are in the same direction. False if they are not in the same direction.

Comments:

 

Example:

vector = Geom::Vector3d.new 0,0,1
vector2 = Geom::Vector3d.new 0,1,0
status = vector.sime_direction? vector2

 
 

set!

The set! method is used to set the coordinates of the vector.

Syntax:

vector2 = vector.set!  x, y, z

vector2 = vector.set! ([x, y, z])

vector3 = vector.set! vector2

Arguments:

x - the x value for the vector

y - the y value for the vector

z - the z value for the vector

vector2 - a Vector3D object

Return Value:

vector2 - The newly set Vector3D object

vector3 - The newly set Vector3D object

Comments:

This is a shortcut for writing:

vec.x = x

vec.y = y

vec.z = z

Example:

vector = Geom::Vector3d.new 0,0,1
vector2 = vector.set! 1,0,0

 
 

to_a

The to_a method retrieves the coordinates of the vector in an Array [x, y, z].

Syntax:

a = vector.to_a

Arguments:

 

Return Value:

a - the coordinates of the vector in an array

Comments:

 

Example:

vector = Geom::Vector3d.new 0,0,1
array = vector.to_a

 
 

to_s

The to_s method is used to format the vector as a String.

Syntax:

s = vector.to_s

Arguments:

 

Return Value:

s - a string representation of vector

Comments:

 

Example:

vector = Geom::Vector3d.new 0,0,1
string = vector.to_s

 
 

transform

The transform method is used to apply a transformation to a vector. The vector is not modified.

Syntax:

vector2 = vector.transform! transformation

Arguments:

transformation - a Transformation object to apply to the vector

Return Value:

vector2 - the newly transformed vector

Comments:

 

Example:

point = Geom::Point3d.new 1,1,1
transform = Geom::Transformation.new point
vector = Geom::Vector3d.new 0,0,1
vector2 = vector.transform transform

 
 

transform!

Apply a Transformation to a vector. The vector itself is modified.

Syntax:

vector2 = vector.transform! transformation

Arguments:

transformation - a Transformation object to apply to the vector

Return Value:

vector2 - the newly transformed vector

Comments:

The vector itself is modified.

Example:

point = Geom::Point3d.new 1,1,1
transform = Geom::Transformation.new point
vector = Geom::Vector3d.new 0,0,1
vector2 = vector.transform! transform

 
 

unitvector?

The unitvector? method is used to see if the vector is a unit vector.

Syntax:

status = vector.unitvector?

Arguments:

 

Return Value:

status - true if the vector is a unit vector. False if the vector is not a unit vector.

Comments:

This is equivalent to vec.length == 1.0

Example:

vector = Geom::Vector3d.new 0,0,1
status = vector.unitvector?

 
 

valid?

The valid? method is used to verify if a vector is valid. A vector is valid if its length is not zero.

Syntax:

status = vector.valid?

Arguments:

 

Return Value:

status - true if the vector is valid. False if the vector is not valid.

Comments:

 

Example:

vector = Geom::Vector3d.new 0,0,1
status = vector.vald?

 
 

x

The x method is used to retrieve the x coordinate of the vector.

Syntax:

x = vector.x

Arguments:

 

Return Value:

x - the x coordinate of the vector

Comments:

 

Example:

vector = Geom::Vector3d.new 1,2,3
x = vector.x


 

x=

The x= method is used to set the x coordinate of the vector.

Syntax:

x = vector.x = x

Arguments:

x - the x coordinate for the vector

Return Value:

x - the newly set x coordinate for the vector

Comments:

 

Example:

vector = Geom::Vector3d.new 1,2,3
x = vector.x=10

 
 

y

The y method is used to retrieve the y coordinate of the vector.

Syntax:

y = vec.y

Arguments:

 

Return Value:

y - the y coordinate of the vector

Comments:

 

Example:

vector = Geom::Vector3d.new 1,2,3
y = vector.y

 
 

y=

Set the y coordinate of the vector.

Syntax:

vec.y = y

Arguments:

y - the y coordinate for the vector

Return Value:

y - the newly set y coordinate for the vector

Comments:

 

Example:

vector = Geom::Vector3d.new 1,2,3
y = vector.y=20

 
 

z

Get the z coordinate of the vector.

Syntax:

z = vec.z

Arguments:

 

Return Value:

z - the z coordinate of the vector

Comments:

 

Example:

vector = Geom::Vector3d.new 1,2,3
z = vector.z

 
 

z=

Set the z coordinate of the vector.

Syntax:

vec.z = z

Arguments:

z- the z coordinate for the vector

Return Value:

z - the newly set z coordinate for the vector

Comments:

 

Example:

vector = Geom::Vector3d.new 1,2,3
z = vector.z=30