class Point3d |
Parent: Object |
|
Methods:linear_combination, new, +, -, ==, [], []=, clone, distance, distance_to_line, distance_to_plane, inspect, offset, offset!, on_line?, on_plane?, project_to_line, project_to_plane, set!, to_a, to_s, transform, transform!, vector_to, x, x=, y, y=, z, z= |
|
Sample Code:point3dtests.rb |
|
To create a point:
Geom::Point3d.new - where the creation method (new) can take a variety of arguments.
Geom::Point3d.new - with no arguments, creates a point at the origin [0,0,0]
Geom::Point3d.new(100,200,300) - creates a point in space with an x value of 100, a y value of 200 and a z value of 300
Geom::Point3d.new 100,200,300 - same as above
You can also create a point directly by simply assigning the x, y and z values to a variable as an array:
pt = [100,200,300]
Class Methods |
linear_combination |
The linear_combination method is used to create a new point as a linear combination of two points. This method is generally used to get a point at some percentage along a line connecting the two points. |
Syntax: |
point = Geom::Point3d.linear_combination(weight1, point1, weight2, point2) |
Arguments: |
weight1 - a weight or percentage point1 - the start point on the line weight2 - a weight or percentage point2 - the end point of the line |
Return Value: |
point - a Point3d object |
Comments: |
A linear combination is a standard term for vector math. It is defined as point = weight1 * point1 + weight2 * point2. |
Example: |
point1
= Geom::Point3d.new 1,1,1 |
new |
The new method is used to create a new 3d point. |
Syntax: |
point = Geom::Point3d.new point = Geom::Point3d.new(x,y) point = Geom::Point3d.new(x,y,z) |
Arguments: |
x - the location along the x axis y - the location along the y axis z - the location along the z axis |
Return Value: |
point - the newly created Point3d object |
Comments: |
With no arguments, this creates a point at the origin (0,0,0). With two values, it creates a point at (x,y,0). |
Example: |
point = Geom::Point3d.new |
Instance Methods |
+ |
The + method is used to add a point and a vector together. |
Syntax: |
point2 = point + vector |
Arguments: |
point - a Point3d object vector - a Vector3d object |
Return Value: |
|
Comments: |
The '+' operator is a fast way to add to the current x, y and z values of a point, or to set the values of a point by adding to other points together. Examples: pt = pt1 + pt2 - Sets pt = [pt1.x+pt2.x, pt1.y+pt2.y, pt1.z+pt2.z] pt = pt + [10,10,10] - Add 10 to the x, y and z values of pt. pt += [10,10,10] -Same result as above. pt = pt1 + pt2 + ... - Sum a series of points. |
Example: |
point1 = Geom::Point3d.new 1,1,1 |
- |
The + method is used to subtract two points to get a vector. See examples under Point3d + |
Syntax: |
vector = point2 - point1 |
Arguments: |
point1 - a Point3d object point2 - a Point3d object |
Return Value: |
vector - a Vector3d object |
Comments: |
|
Example: |
point1 = Geom::Point3d.new 1,1,1 |
== |
The == method is used to compare two points for equality. |
Syntax: |
status = point1 == point2 |
Arguments: |
point1 - a Point3d object point2 - a Point3d object |
Return Value: |
status - true if both points are equal; false if points are not equal |
Comments: |
This uses the standard SketchUp tolerance
to determine if two points are the same. if( pt1 == pt2 ) ... or if( pt1 == [100,200,300] ) ... |
Example: |
point1 = Geom::Point3d.new 1,1,1 |
[] |
The [] method is used to retrieve the value of the point at the specified index. |
Syntax: |
value = point[index] |
Arguments: |
index - the index for a specific x,y, or z value within the Point3d |
Return Value: |
value - an x, y, or z value if successful |
Comments: |
|
Example: |
point = Geom::Point3d.new 1,2,3 |
[]= |
The []= method is used to set the x, y, or z value of the point based on the specific index of the value. |
Syntax: |
status = point[n] = new_value |
Arguments: |
new_value - new x, y, or z value |
Return Value: |
status - the newly set x, y, or z value if successful |
Comments: |
pt[0] = xval pt[1] = yval pt[2] = zval |
Example: |
point = Geom::Point3d.new 1,2,3 |
clone |
The clone method is used to create another point identical to the point being cloned. |
Syntax: |
point2 = point.clone |
Arguments: |
|
Return Value: |
point2 - the cloned Point3d object |
Comments: |
|
Example: |
point = Geom::Point3d.new 1,2,3 |
distance |
The distance method is used to compute the distance from a point to another point. |
Syntax: |
distance = point1.distance point2 |
Arguments: |
point2 - the Point3d object to compute the distance to |
Return Value: |
distance - the distance in current units |
Comments: |
|
Example: |
point1 = Geom::Point3d.new 1,1,1 |
distance_to_line |
The distance_to_line method is used to compute the distance from a point to a line. |
Syntax: |
distance = point.distance_to_line line |
Arguments: |
line - a line (see Geom for information on creating lines) |
Return Value: |
distance - the distance between a point and line in current units if successful |
Comments: |
See module Geom for how to specify a line. |
Example: |
point1 = Geom::Point3d.new 1,1,1 |
distance_to_plane |
The distance_to_plane method is used to compute the distance from the point to a plane. |
Syntax: |
distance = point.distance_to_plane plane |
Arguments: |
plane - a plane (see Geom for how to create a plane) |
Return Value: |
distance - a distance between a point and a plane in current units if successful |
Comments: |
See module Geom for how to specify a plane. |
Example: |
point1 = Geom::Point3d.new 1,1,1 |
inspect |
The inspect method is used to format a 3d point as a string. |
Syntax: |
string = point.inspect |
Arguments: |
|
Return Value: |
point - a string point representation |
Comments: |
You will not often use these function
directly. Instead, they are called automatically |
Example: |
point = Geom::Point3d.new 10,10,10 |
offset |
The offset method is used to offset a point by a vector. |
Syntax: |
point2 = point1.offset(vector) point2 = point1.offset(vector, distance) |
Arguments: |
vector - a Vector3d object to offset the point by distance - a distance |
Return Value: |
point2 - a new Point3d object |
Comments: |
In the second form, the point is offset in the direction of the vector by the given distance. The length of the vector must not be zero. |
Example: |
point1 = Geom::Point3d.new 10,10,10 |
offset! |
The offset! method is used to offset a point by a vector. The point itself is modified. |
Syntax: |
point2 = point.offset! vector |
Arguments: |
vector - a Vector3d object to offset the point by |
Return Value: |
point2 - a new Point3d object |
Comments: |
Unlike offset, the point itself is modified. |
Example: |
point = Geom::Point3d.new 10,10,10 |
on_line? |
The on_line? method is used to determine if the point is on a line. |
Syntax: |
status = point.on_line? line |
Arguments: |
line - a line (see Geom for how to create a line) |
Return Value: |
status - true if the point is on the line; false if the point is not on the line |
Comments: |
See module Geom for how to specify a line. |
Example: |
line = [Geom::Point3d.new(0,0,0),
Geom::Vector3d.new(0,0,1) |
on_plane? |
The on_plane? method is used to determine if the point is on a plane. |
Syntax: |
status = point.on_plane? point, normal status = point.on_plane? A, B, C, D |
Arguments: |
|
Return Value: |
status - true if the point is on the plane; false if the point is not on the plane |
Comments: |
See module Geom for how to specify a line. |
Example: |
plane
= [Geom::Point3d.new(0,0,0), Geom::Vector3d.new(0,0,1)] |
project_to_line |
The project_to_line method is used to retrieve the point on a line that is closest to this point. |
Syntax: |
point = point.project_to_line line |
Arguments: |
line - a line (see Geom for how to create a line) |
Return Value: |
point - the Point3d that is on a line closest to the point |
Comments: |
The line may be defined by either a point and a vector or by two points. |
Example: |
|
project_to_plane |
The project_to_plane method is used to retrieve the point on a plane that is closest to the point. |
Syntax: |
point = point.project_to_plane plane |
Arguments: |
plane - a plane (see Geom for how to create a plane) |
Return Value: |
point - the Point3d that is on a plane closest to the point |
Comments: |
The plane may be defined by either a point on the plane and a vector perpendicular to the plane or by the coeficients to the plane equation AX + BY + CZ + D = 0 |
Example: |
|
set! |
The set method forces a point to a specific x, y, z coordinate. |
Syntax: |
point = point.set! newx, newy, newz |
Arguments: |
newx - new X value newy - new Y value newz - new Z value |
Return Value: |
point - the new Point3d |
Comments: |
pt.set!([100,200,300]) sets pt.x = 100, pt.y = 200, pt.z = 300. Alternatively,
you can set pt1.set!(pt2) sets pt1 x, y and z values to be the same as pt2. |
Example: |
point = Geom::Point3d.new 10,10,10 |
to_a |
The to_a method is used to convert the point to an array of 3 numbers |
Syntax: |
array = pt.to_a |
Arguments: |
|
Return Value: |
array - an array of three numbers representing x,y,z of the Point3d |
Comments: |
pt = [100,200,300] pt.to_a outputs [100.0,200.0,300.0] |
Example: |
point = Geom::Point3d.new 10,20,30 |
to_s |
The to_s method is used to retrieve a string representation of a point. |
Syntax: |
string = pt.to_s |
Arguments: |
|
Return Value: |
string - the string representation of the Point3d |
Comments: |
|
Example: |
point = Geom::Point3d.new 10,10,10 |
transform |
The transform method is used to create a new point by applying a transformation to a point. |
Syntax: |
point2 = point.transform transformation |
Arguments: |
transformation - a Transformation object |
Return Value: |
point2 - the transformed Point3d object |
Comments: |
|
Example: |
transform = Geom::Transformation.new(point2) |
transform! |
The transform! method is used to apply a Transformation to a point. |
Syntax: |
point.transform! transformation |
Arguments: |
transformation - a Transformation object |
Return Value: |
|
Comments: |
Unlike the transform method, the point itself is modified. |
Example: |
transform = Geom::Transformation.new(point2) |
vector_to |
The vector_to team method retrieves the vector between points. |
Syntax: |
vector = point1.vector_to point2 |
Arguments: |
point2 - a Point3d object |
Return Value: |
vector - a Vector object |
Comments: |
pt1 = [1,1,0] pt2 = [3,1,0] pt1.vector_to( pt2 ) returns the vector (2,0,0) pt1.vector_to(pt2) is equivalent to (pt2 - pt1) |
Example: |
point2 = Geom::Point3d.new 100,200,300 |
x |
The x method retrieves the x value of the 3d point. |
Syntax: |
x = point.x |
Arguments: |
|
Return Value: |
x - the new x value |
Comments: |
|
Example: |
point = Geom::Point3d.new 1,2,3 |
x= |
The x= method is used to set the x value of a 3d point. |
Syntax: |
x= point.x = value |
Arguments: |
value - the new x value |
Return Value: |
x - the newly set x value |
Comments: |
|
Example: |
point = Geom::Point3d.new 1,2,3 |
y |
The y method retrieves the y value of the 3d point. |
Syntax: |
y = point.y |
Arguments: |
|
Return Value: |
y - the new y value |
Comments: |
|
Example: |
point = Geom::Point3d.new 1,2,3 |
y= |
The y= method is used to set the y value of a 3d point. |
Syntax: |
y = point.y = value |
Arguments: |
value - the new y value |
Return Value: |
y - the newly set y value |
Comments: |
|
Example: |
point = Geom::Point3d.new 1,2,3 |
z |
The z method retrieves the z value of the 3d point. |
Syntax: |
z = point.z |
Arguments: |
|
Return Value: |
z - the z value |
Comments: |
|
Example: |
point = Geom::Point3d.new 1,2,3 |
z= |
The z= method is used to set the z value of a 3d point. |
Syntax: |
point.z = value |
Arguments: |
value - the new z value |
Return Value: |
z - the newly set z value |
Comments: |
|
Example: |
point = Geom::Point3d.new 1,2,3 |