Point3d

class Point3d

Parent: Object | Class Index
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 |

The Point3d class allows you to work with a point in 3d space.
The point is basically just a series of values representing x, y and z coordinates. The values are specified as [x,y,z]. For example [100,200,300].

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
point2 = Geom::Point3d.new 10,10,10
# Gets the point on the line segment connecting point1 and point2 that is
# 3/4 the way from point1 to point2.
point = Geom::Point3d.linear_combination 0.25, point1, 0.75, point2
if (point)
UI.messagebox point
else
UI.messagebox "Failure"
end

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 vector = Geom::Vector3d.new 10,10,10 point3 = point1 + vector

-
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 point2 = Geom::Point3d.new 10,10,10 vector = point2-point1

==
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. Points can be compared to one another or to an array representing x, y and z coordinates, as in the following examples: if( pt1 == pt2 ) ... or if( pt1 == [100,200,300] ) ...
Example:
point1 = Geom::Point3d.new 1,1,1 point2 = Geom::Point3d.new 10,10,10 status = point1 == point2

[]
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 # retrieves the y value yvalue = point[1]

[]=
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 yvalue = point[1] = 4

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 newpoint = point.clone

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 point2 = Geom::Point3d.new 10,10,10 distance = point1.distance point2

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 point2 = Geom::Point3d.new 10,10,10 distance = point1.distance point2

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 point2 = Geom::Point3d.new 10,10,10 distance = point1.distance point2

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 when an object is output using a print command like 'puts', which writes to the Ruby console
Example:
point = Geom::Point3d.new 10,10,10 string = point.inspect

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 vector = Geom::Vector3d.new(0,0,1) point2 = point1.offset vector

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 vector = Geom::Vector3d.new(0,0,1) point2 = point1.offset! vector

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) point = Geom::Point3d.new 10,10,10 status = point.on_line? line

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)] point = Geom::Point3d.new 10,10,10 status = point.on_plane? plane

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 one point to another. pt1.set!(pt2) sets pt1 x, y and z values to be the same as pt2.
Example:
point = Geom::Point3d.new 10,10,10 status = point.set! 100,200,300

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 array = point.to_a

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 str = point.to_s

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) point2 = Geom::Point3d.new 100,200,300 point1 = Geom::Point3d.new 10,10,10 point3 = point1.transform transform

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) point2 = Geom::Point3d.new 100,200,300 point1 = Geom::Point3d.new 10,10,10 point3 = point1.transform! transform

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 point1 = Geom::Point3d.new 10,10,10 vector = point1.vector_to point2

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 = point.x

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 x = point.x=2

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 = point.y

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 y = point.y=2

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 = point.x

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 z = point.z=2