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