|
SketchUp Ruby API Reference |
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.
Parent: Object
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=
Example Code: vector3dtests.rb
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.
vector = Geom::Vector3d.linear_combination(weight1, vector1, weight2, vector2)
vector = Geom::Vector3d.linear_combination(x, xaxis, y, yaxis, z, zaxis)
weight1 - a weight or percentage
vector1 - the first vector
weight2 - a weight or percentage
vector2 - the end point of the line
vector - a Vector3d object
A linear combination is a standard term for vector math. It is defined as point = weight1 * point1 + weight2 * point2.
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
The new method is used to create a new vector.
vector = Geom::Vector3d.new
vector = Geom::Vector3d.new(x, y, z)
vector = Geom::Vector3d.new(vector2)
x - a X value
y - a Y value
z - a Z value
vector2 - a Vector3d object
vector - a vector3d object
# 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
The % method is used to compute the dot product between two vectors.
d = vector1 % vector2
vector1 - a Vector3d object
vector 2 - a Vector3d object
d - the dot product if successful
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.
# 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.
vector = vector1 * vector2
vector1 - a Vector3d object
vector2 - a Vector3d object
vector - a Vector3d object if successful
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.
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.
vector = vector1 + vector2
vector1 - a Vector3d object
vector2 - a Vector3d object
vector - a Vector3d object if successful
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.
vector = vector1 - vector2
vector1 - a Vector3d object
vector2 - a Vector3d object
vector - a Vector3d object if successful
The == method is used to determine if two vectors are equal to within tolerance.
status = vector1 == vector2
vector1 - a Vector3d object
vector2 - a Vector3d object
status - true if vector1 is equal to vector 2. False if they are not equal.
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.
coordinate = vector[i]
i - an index into an array of three coordinates.
coordinate - the value for the x, y, or z coordinate.
The following are equivalent:
x = vector.x
x = vector[0]
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.
value = vector[i] = coordinate
coordinate - the value for the x, y, or z coordinate.
value - the newly set coordinate value
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
The angle_between method is used to compute the angle (in radians) between this vector and another vector.
angle = vector.angle_between vector2
vector2 - a Vector3d object
angle - an angle (in radians)
vector = Geom::Vector3d.new 1,0,0
vector2 = Geom::Vector3d.new 0,1,0
status = vector == vector2
angle = vector.angle_between vector2
The axes method is used to compute an arbitrary set of axes with the given vector as the z-axis direction.
a = vector.axes
a - an Array object containing three Vector3d objects
Returns an Array of three vectors [xaxis, yaxis, zaxis]
vector = Geom::Vector3d.new 1,0,0
a = vector.axes
The clone method is used to make a copy of a vector.
vector2 = vector.clone
vector2 - a Vector3d object which is the clone of vector
This method is equivalent to vec2 = Geom::Vector3d.new(vec)
vector = Geom::Vector3d.new 1,0,0
vector2 = vector.clone
The cross method is used to compute the cross product between two vectors.
vector = vector1.cross vector2
vector2 - a Vector3d object
vector - the cross of vector1 and vector2
vector = Geom::Vector3d.new 1,0,0
vector2 = Geom::Vector3d.new 0,1,0
v = vector.cross vector2
The dot method is used to compute the dot product between two vectors.
d = vector1.dot vector2
vector2 - a Vector3d object
d - the dot product of vector1 and vector2
vector = Geom::Vector3d.new 0,0,1
vector2 = Geom::Vector3d.new 0,1,0
d = vector.dot vector2
The inspect method is used to inspect the contents of a vector.
vector = vector.inspect
vector - the Vector3d object
vector = Geom::Vector3d.new 0,0,1
v = vector.inspect
The length method is used to retrieve the length of the vector.
length = vector.length
length - the length of the vector
vector = Geom::Vector3d.new 0,0,1
l = vector.length
The length= method is used to set the length of the vector. The length must be greater than 0.
length = vector.length = length
length - a length for the vector
length - a newly set length
vector = Geom::Vector3d.new 0,0,1
l = vector.length
UI.messagebox l
newl = vector.length = 2
The normalize method is used to retrieve a unit vector in the same direction as this vector.
vector2 = vector.normalize
vector2 - a normalized Vector3d object
vector = Geom::Vector3d.new 0,0,1
vector2 = vector.normalize
The normalize! method is used to convert a vector into a unit vector. Another way to do this is vec.length = 1
vector2 - vector.normalize!
vector2 - a normalized Vector3d object
vector = Geom::Vector3d.new 0,0,1
vector2 = vector.normalize!
The parallel method is used to determine if this vector is parallel to another vector to within tolerance.
status = vector.parallel? vector2
vector2 - a Vector3d object
status - true if vector and vector2 are parallel. False if they are not parallel.
vector = Geom::Vector3d.new 0,0,1
vector2 = Geom::Vector3d.new 0,1,0
status = vector.parallel? vector2
The perpendicular? method is used to determine if this vector is perpendicular to another vector to within tolerance.
status = vector.perpendicular? vector2
vector2 - a Vector3d object
status - true if vector and vector2 are parallel. False if they are not parallel.
vector = Geom::Vector3d.new 0,0,1
vector2 = Geom::Vector3d.new 0,1,0
status = vector.perpendicular? vector2
The reverse method is used to retrieve a new vector that is the reverse of this vector.
vector2 = vector.reverse
vector2 - a Vector3d object that is the reverse of vector
vector = Geom::Vector3d.new 0,0,1
vector2 = vector.reverse
The reverse! method is used to retrieve the reverse the vector.
vector2 = vector.reverse!
vector2 - a Vector3d object that is the reverse of vector
vector = Geom::Vector3d.new 0,0,1
vector2 = vector.reverse!
The samedirection? method is used to determine if this vector is parallel to and in the same direction as another vector to within tolerance.
status = vector.same_direction? vector2
vector2 - a Vector3D object
status - true if vector and vector2 are in the same direction. False if they are not in the same direction.
vector = Geom::Vector3d.new 0,0,1
vector2 = Geom::Vector3d.new 0,1,0
status = vector.sime_direction? vector2
The set! method is used to set the coordinates of the vector.
vector = vector.set! x, y, z
vector = vector.set! ([x, y, z])
vector = vector.set! vector2
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
vector - The newly set Vector3D object
This is a shortcut for writing:
vec.x = x
vec.y = y
vec.z = z
vector = Geom::Vector3d.new 0,0,1
vector2 = vector.set! 1,0,0
The to_a method retrieves the coordinates of the vector in an Array [x, y, z].
a = vector.to_a
a - the coordinates of the vector in an array
vector = Geom::Vector3d.new 0,0,1
array = vector.to_a
The to_s method is used to format the vector as a String.
s = vector.to_s
s - a string representation of vector
vector = Geom::Vector3d.new 0,0,1
string = vector.to_s
The transform method is used to apply a transformation to a vector. The vector is not modified.
vector2 = vector.transform! transformationtransformation - a Transformation object to apply to the vector
vector2 - the newly transformed vector
point = Geom::Point3d.new 1,1,1
transform = Geom::Transformation.new point
vector = Geom::Vector3d.new 0,0,1
vector2 = vector.transform transform
Apply a Transformation to a vector. The vector itself is modified.
vector2 = vector.transform! transformation
transformation - a Transformation object to apply to the vector
vector2 - the newly transformed vector
The vector itself is modified.
point = Geom::Point3d.new 1,1,1
transform = Geom::Transformation.new point
vector = Geom::Vector3d.new 0,0,1
vector2 = vector.transform! transform
The unitvector? method is used to see if the vector is a unit vector.
status = vector.unitvector?
status - true if the vector is a unit vector. False if the vector is not a unit vector.
This is equivalent to vec.length == 1.0
vector = Geom::Vector3d.new 0,0,1
status = vector.unitvector?
The valid? method is used to verify if a vector is valid. A vector is valid if its length is not zero.
status = vector.valid?
status - true if the vector is valid. False if the vector is not valid.
vector = Geom::Vector3d.new 0,0,1
status = vector.vald?
The x method is used to retrieve the x coordinate of the vector.
x = vector.x
x - the x coordinate of the vector
vector = Geom::Vector3d.new 1,2,3
x = vector.x
The x= method is used to set the x coordinate of the vector.
x = vector.x = x
x - the x coordinate for the vector
x - the newly set x coordinate for the vector
vector = Geom::Vector3d.new 1,2,3
x = vector.x=10
The y method is used to retrieve the y coordinate of the vector.
y = vec.y
y - the y coordinate of the vector
vector = Geom::Vector3d.new 1,2,3
y = vector.y
Set the y coordinate of the vector.
vec.y = y
y - the y coordinate for the vector
y - the newly set y coordinate for the vector
vector = Geom::Vector3d.new 1,2,3
y = vector.y=20
Get the z coordinate of the vector.
z = vec.z
z - the z coordinate of the vector
vector = Geom::Vector3d.new 1,2,3
z = vector.z
Set the z coordinate of the vector.
vec.z = z
z- the z coordinate for the vector
z - the newly set z coordinate for the vector
vector = Geom::Vector3d.new 1,2,3
z = vector.z=30
|
SketchUp Ruby API Reference: Vector3d |
© Google Inc. 2007 sketchup.google.com |