Vector3d

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