# Class: Geom::Point3d

Inherits:
Object
• Object
show all

## Overview

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 call Geom::Point3d.new, where the creation method can take a variety of arguments:

In addition to the methods below, there are a series of geometry related methods that are on the Array class, since Point3d objects can also be represented as a 3-element Array. These Array-level methods are for operations such as determining if a point is on a line, on a plane, etc. See the Array class for details.

Examples:

``````# No arguments, creates a point at the origin [0,0,0]
pt1 = Geom::Point3d.new

# Creates a point at x of 100, y of 200, z of 300.
pt2 = Geom::Point3d.new(100,200,300)

# You can also create a point directly by simply assigning the x, y and z
# values to a variable as an array:
pt3 = [100,200,300]``````

Version:

• SketchUp 6.0

## Class Method Summary collapse

• The linear_combination method is used to create a new point as a linear combination of two points.

## Instance Method Summary collapse

• 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.

• The '-' operator is a fast way to subtract from the current x, y and z values of a point.

• The '<' operator is a fast way to determine if another point is closer to the origin.

• The == method is used to compare two points for equality.

• The [] method is used to retrieve the value of the point at the specified index.

• The []= method is used to set the x, y, or z value of the point based on the specific index of the value.

• The clone method is used to create another point identical to the point being cloned.

• The distance method is used to compute the distance from a point to another point.

• The distance_to_line method is used to compute the distance from a point to a line.

• The distance_to_plane method is used to compute the distance from the point to a plane.

• constructor

The new method is used to create a new 3D point.

• The inspect method is used to format a 3D point as a string.

• The offset method is used to offset a point by a vector and return a new point.

• The offset! method is used to offset a point by a vector.

• The on_line? method is used to determine if the point is on a line.

• The on_plane? method is used to determine if the point is on a plane.

• The project_to_line method is used to retrieve the point on a line that is closest to this point.

• The project_to_plane method is used to retrieve the point on a plane that is closest to the point.

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

• The to_a method is used to convert the point to an array of 3 numbers.

• The to_s method is used to retrieve a string representation of a point.

• The transform! method is used to apply a Transformation to a point.

• The transform! method is used to apply a Transformation to a point to create a new point.

• The vector_to team method retrieves the vector between points.

• The x method retrieves the x value of the 3D point.

• The x= method is used to set the x value of a 3D point.

• The y method retrieves the y value of the 3D point.

• The y= method is used to set the y value of a 3D point.

• The z method retrieves the z value of the 3D point.

• The z= method is used to set the z value of a 3D point.

## Constructor Details

### #initialize(x, y, z) ⇒ Object

The new method is used to create a new 3D point.

With no arguments, this creates a point at the origin (0,0,0). With two values, it creates a point at (x,y,0).

Examples:

``````# No arguments, creates a point at the origin [0,0,0]
pt1 = Geom::Point3d.new

# Creates a point at x of 100, y of 200, z of 300.
pt2 = Geom::Point3d.new(100,200,300)

# You can also create a point directly by simply assigning the x, y and z
# values to a variable as an array:
pt3 = [100,200,300]``````

Returns point - the newly created Point3d object

Parameters:

• x

The location along the x axis.

• y

The location along the y axis.

• z

The location along the z axis.

Version:

• SketchUp 6.0

## Class Method Details

### .linear_combination(weight1, point1, weight2, point2) ⇒ Object

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.

A linear combination is a standard term for vector math. It is defined as point = weight1 * point1 + weight2 * point2.

Examples:

``````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``````

Returns point - a Point3d object

Parameters:

• weight1

A weight or percentage.

• point1

The start point on the line.

• weight2

A weight or percentage.

• point2

The end point of the line.

Returns:

• point - a Point3d object

Version:

• SketchUp 6.0

## Instance Method Details

### #+(point2) ⇒ Object

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:

``````pt2 = pt + vec
pt = pt + [10,10,10]``````

Returns point - a Point3d object

Parameters:

• point2

A Point3d object.

Returns:

• point - a Point3d object

Version:

• SketchUp 6.0

### #-(point2) ⇒ Object

The '-' operator is a fast way to subtract from the current x, y and z values of a point.

Examples:

``````pt2 = pt - vec
pt = pt - [10,10,10]``````

Returns vector - a Vector object

Parameters:

• point2

A Point3d object.

Returns:

• vector - a Vector object

Version:

• SketchUp 6.0

### #<(point2) ⇒ Object

The '<' operator is a fast way to determine if another point is closer to the origin.

Examples:

``````pt1 = Geom::Point3d.new(10,10,10)
pt2 = Geom::Point3d.new(20,20,20)
result = pt1 < pt2``````

Returns true if the point2 is closer to the origin.

Parameters:

• point2

A Point3d object.

Returns:

• true if the point2 is closer to the origin.

Version:

• SketchUp 6.0

### #==(point2) ⇒ Object

The == method is used to compare two points for equality.

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:

Examples:

``````if( pt1 == pt2 )
UI.messagebox('equal')
end

# ... or ...
if( pt1 == [100,200,300] ) ...
UI.messagebox('equal')
end``````
``````point1 = Geom::Point3d.new 1,1,1
point2 = Geom::Point3d.new 10,10,10
status = point1 == point2``````

Returns status - true if both points are equal; false if points are not equal

Parameters:

• point2

A Point3d object.

Returns:

• status - true if both points are equal; false if points are not equal

Version:

• SketchUp 6.0

### #[](index) ⇒ Object

The [] method is used to retrieve the value of the point at the specified index.

Examples:

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

# retrieves the y value of 2
yvalue = point[1]``````

Returns value - an x, y, or z value if successful

Parameters:

• index

The index for a specific x, y, or z value within the Point3d.

Returns:

• value - an x, y, or z value if successful

Version:

• SketchUp 6.0

### #[]=(new_value) ⇒ Object

The []= method is used to set the x, y, or z value of the point based on the specific index of the value.

Examples:

``````point = Geom::Point3d.new 1,2,3
yvalue = point[1] = 4``````

Returns status - the newly set x, y, or z value if successful

Parameters:

• new_value

New x, y, or z value.

Returns:

• status - the newly set x, y, or z value if successful

Version:

• SketchUp 6.0

### #clone ⇒ Object

The clone method is used to create another point identical to the point being cloned.

Examples:

``````point = Geom::Point3d.new 1,2,3
newpoint = point.clone``````

Returns:

• point2 - the cloned Point3d object

Version:

• SketchUp 6.0

### #distance(point2) ⇒ Object

The distance method is used to compute the distance from a point to another point.

Examples:

``````point1 = Geom::Point3d.new 1,1,1
point2 = Geom::Point3d.new 10,10,10
distance = point1.distance point2``````

Returns distance - the distance in current units

Parameters:

• point2

The Point3d object to compute the distance to.

Returns:

• distance - the distance in current units

Version:

• SketchUp 6.0

### #distance_to_line(line) ⇒ Object

The distance_to_line method is used to compute the distance from a point to a line.

See Geom module for how to specify a line.

Examples:

``````point1 = Geom::Point3d.new 1,1,1
line = [Geom::Point3d.new(0,0,0), Geom::Vector3d.new(0,0,1)]
distance = point1.distance_to_line line``````

Returns distance - the distance between a point and line in current units if successful

Parameters:

• line

A line (see Geom for information on creating lines).

Returns:

• distance - the distance between a point and line in current units if successful

Version:

• SketchUp 6.0

### #distance_to_plane(plane) ⇒ Object

The distance_to_plane method is used to compute the distance from the point to a plane.

See module Geom for how to specify a plane.

Examples:

``distance = point.distance_to_plane plane``

Returns distance - a distance between a point and a plane in current units if successful

Parameters:

• plane

A plane (see Geom for how to create a plane).

Returns:

• distance - a distance between a point and a plane in current units if successful

Version:

• SketchUp 6.0

### #inspect ⇒ Object

The inspect method is used to format a 3D point as a string.

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.

Examples:

``````point = Geom::Point3d.new 10,10,10
string = point.inspect``````

Returns:

• point - a string point representation

Version:

• SketchUp 6.0

### #offset(vector, length = vector.length) ⇒ Object

The offset method is used to offset a point by a vector and return a new point. The length of the vector must not be zero.

Examples:

``````point1 = Geom::Point3d.new(10,10,10)
vector = Geom::Vector3d.new(0,0,1)
point2 = point1.offset! vector``````

Returns point2 - a new Point3d object

Parameters:

• vector

A Vector3d object to offset the point by.

• length (defaults to: vector.length)

the distance to offset. If not provided, the offset is my a distance equal to the vector length.

Returns:

• point2 - a new Point3d object

Version:

• SketchUp 6.0

### #offset!(vector, length = vector.length) ⇒ Object

The offset! method is used to offset a point by a vector. The point itself is modified.

Unlike offset, the point itself is modified.

Examples:

``````point1 = Geom::Point3d.new(10,10,10)
vector = Geom::Vector3d.new(0,0,1)
point2 = point1.offset! vector``````

Returns point2 - a new Point3d object

Parameters:

• vector

A Vector3d object to offset the point by.

• length (defaults to: vector.length)

the distance to offset. If not provided, the offset is my a distance equal to the vector length.

Returns:

• point2 - a new Point3d object

Version:

• SketchUp 6.0

### #on_line?(line) ⇒ Object

The on_line? method is used to determine if the point is on a line.

See module Geom for the various ways to specify a line.

Examples:

``````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``````

Returns status - true if the point is on the line; false if the point is not on the line

Parameters:

• line

A line (see Geom for how to create a line).

Returns:

• status - true if the point is on the line; false if the point is not on the line

Returns:

• (Boolean)

Version:

• SketchUp 6.0

### #on_plane?(plane) ⇒ Object

The on_plane? method is used to determine if the point is on a plane.

See module Geom for the various ways to specify a plane.

Examples:

``````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``````

Returns status - true if the point is on the plane; false if the point is not on the plane

Parameters:

• plane

Returns:

• status - true if the point is on the plane; false if the point is not on the plane

Returns:

• (Boolean)

Version:

• SketchUp 6.0

### #project_to_line(line) ⇒ Object

The project_to_line method is used to retrieve the point on a line that is closest to this point.

The line may be defined by either a point and a vector or by two points.

Examples:

``````line = [Geom::Point3d.new(0,0,0), Geom::Vector3d.new(0,0,1)]
point = Geom::Point3d.new 10,10,10
projected_point = point.project_to_line line``````

Returns point - the Point3d that is on a line closest to the point

Parameters:

• line
• see Geom for how to specify a line

Returns:

• point - the Point3d that is on a line closest to the point

Version:

• SketchUp 6.0

### #project_to_plane(plane) ⇒ Object

The project_to_plane method is used to retrieve the point on a plane that is closest to the point.

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. See Geom for details.

Examples:

``````plane = [Geom::Point3d.new(0,0,0), Geom::Vector3d.new(0,0,1)]
point = Geom::Point3d.new 10,10,10
projected_point = point.project_to_plane plane``````

Returns point - the Point3d that is on a plane closest to the point

Parameters:

• plane

A plane (see Geom for how to create a plane).

Returns:

• point - the Point3d that is on a plane closest to the point

Version:

• SketchUp 6.0

### #set!(x, y, z) ⇒ Object

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

Examples:

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

Returns point - the newly created Point3d object

Parameters:

• x

The location along the x axis .

• y

The location along the y axis.

• z

The location along the z axis.

Returns:

• point - the newly created Point3d object

Version:

• SketchUp 6.0

### #to_a ⇒ Object

The to_a method is used to convert the point to an array of 3 numbers

Examples:

``````point = Geom::Point3d.new 10,20,30
array = point.to_a

pt = [100,200,300]
# outputs [100.0,200.0,300.0]
UI.messagebox(pt.to_a)``````

Returns:

• array - an array of three numbers representing x,y,z of the Point3d

Version:

• SketchUp 6.0

### #to_s ⇒ Object

The to_s method is used to retrieve a string representation of a point.

Examples:

``````point = Geom::Point3d.new 10,10,10
str = point.to_s``````

Returns:

• string - the string representation of the Point3d

Version:

• SketchUp 6.0

### #transform!(transform) ⇒ Object

The transform! method is used to apply a Transformation to a point.

Unlike the transform method, the point itself is modified.

Examples:

``````transform = Geom::Transformation.new(point2)
point2 = Geom::Point3d.new 100,200,300
point1 = Geom::Point3d.new 10,10,10
point1.transform! transform``````

Returns nil

Parameters:

• transform

A Transformation object.

Returns:

• nil

Version:

• SketchUp 6.0

### #transform(transform) ⇒ Object

The transform! method is used to apply a Transformation to a point to create a new point.

Examples:

``````transform = Geom::Transformation.new(point2)
point2 = Geom::Point3d.new 100,200,300
point1 = Geom::Point3d.new 10,10,10
point3 = point1.transform transform``````

Returns transformed_point - the new point

Parameters:

• transform

A Transformation object.

Returns:

• transformed_point - the new point

Version:

• SketchUp 6.0

### #vector_to(point2) ⇒ Object

The vector_to team method retrieves the vector between points.

Examples:

``````point2 = Geom::Point3d.new 100,200,300
point1 = Geom::Point3d.new 10,10,10
vector = point1.vector_to point2

# Another example...
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)``````

Returns vector - a Vector object

Parameters:

• point2

A Point3d object.

Returns:

• vector - a Vector object

Version:

• SketchUp 6.0

### #x ⇒ Object

The x method retrieves the x value of the 3D point.

Examples:

``````point = Geom::Point3d.new 1,2,3
x = point.x``````

Returns:

• x - the new x value

Version:

• SketchUp 6.0

### #x=(value) ⇒ Object

The x= method is used to set the x value of a 3D point.

Examples:

``````point = Geom::Point3d.new 1,2,3
x = point.x = 2``````

Returns x - the newly set x value

Parameters:

• value

The new x value.

Returns:

• x - the newly set x value

Version:

• SketchUp 6.0

### #y ⇒ Object

The y method retrieves the y value of the 3D point.

Examples:

``````point = Geom::Point3d.new 1,2,3
y = point.y``````

Returns:

• y - the new y value

Version:

• SketchUp 6.0

### #y=(value) ⇒ Object

The y= method is used to set the y value of a 3D point.

Examples:

``````point = Geom::Point3d.new 1,2,3
y = point.y = 2``````

Returns y - the newly set y value

Parameters:

• value

The new y value.

Returns:

• y - the newly set y value

Version:

• SketchUp 6.0

### #z ⇒ Object

The z method retrieves the z value of the 3D point.

Examples:

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

Returns:

• z - the z value

Version:

• SketchUp 6.0

### #z=(value) ⇒ Object

The z= method is used to set the z value of a 3D point.

Examples:

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

Returns z - the newly set z value

Parameters:

• value

The new z value.

Returns:

• z - the newly set z value

Version:

• SketchUp 6.0