Point3d class

 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]

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=

Example Code: point3dtests.rb

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

- 

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

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

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 

Return Value

point2 - the cloned Point3d object

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

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 

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

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

Argument

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.

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

point = Geom::Point3d.new 10,10,10
status = point.set! 100,200,300

set!

The set! method is used to set the values of the Point3d.

Syntax

status = point.set! 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

Example

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

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 

Return Value

string - the string representation of the Point3d

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

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

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 

Return Value

x - the new x value

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

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

Return Value

y - the new y value

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

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

Return Value

z - the z value

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

Example

point = Geom::Point3d.new 1,2,3
z = point.z=2