123456789_123456789_123456789_123456789_123456789_

Class: Geom::Point3d

Relationships
Inherits: Object

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

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new ⇒ Point3d .new(x, y, z = 0.0) ⇒ Point3d .new(point3d) ⇒ Point3d .new(array3d) ⇒ Point3d .new(array2d) ⇒ Point3d .new(input_point) ⇒ Point3d .new(vertex) ⇒ Point3d

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

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]

Overloads:

  • .new ⇒ Point3d
  • .new(x, y, z = 0.0) ⇒ Point3d

    Parameters:

    • x (Numeric) —

      The location along the x axis.

    • y (Numeric) —

      The location along the y axis.

    • z (Numeric) (defaults to: 0.0) —

      The location along the z axis.

  • .new(point3d) ⇒ Point3d

    Parameters:

    • point3d (Point3d)
  • .new(array3d) ⇒ Point3d

    Parameters:

  • .new(array2d) ⇒ Point3d

    Parameters:

  • .new(input_point) ⇒ Point3d

    Parameters:

  • .new(vertex) ⇒ Point3d

    Parameters:

Version:

  • SketchUp 6.0

Class Method Details

.linear_combination(weight1, point1, weight2, point2) ⇒ Point3d

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)

# Get the point that is half the way from point1 to point2.
points = Geom::Point3d.linear_combination(0.5, point1, 0.5, point2)

# Get the point that is 3/4 the way from point1 to point2.
point = Geom::Point3d.linear_combination(0.25, point1, 0.75, point2)

# Get the point that is 70% the way from point1 to point2.
percentage = 0.7
point = Geom::Point3d.linear_combination(1.0 - percentage, point1, percentage, point2)

Parameters:

  • weight1 (Float)
  • point1 (Point3d)
  • weight2 (Float)
  • point2 (Point3d)

Version:

  • SketchUp 6.0

Instance Attribute Details

#x ⇒ Length (rw)

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0

#x=(value) ⇒ Numeric (rw)

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

Parameters:

  • value (Numeric) —

    The new x value.

Returns:

  • (Numeric) —

    the newly set x value

Version:

  • SketchUp 6.0

#y ⇒ Length (rw)

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0

#y=(value) ⇒ Numeric (rw)

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

Parameters:

  • value (Numeric) —

    The new y value.

Returns:

  • (Numeric) —

    the newly set y value

Version:

  • SketchUp 6.0

#z ⇒ Length (rw)

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0

#z=(value) ⇒ Numeric (rw)

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

Parameters:

  • value (Numeric) —

    The new z value.

Returns:

  • (Numeric) —

    the newly set z value

Version:

  • SketchUp 6.0

Instance Method Details

#+(vector) ⇒ Point3d

The #+ operator is a fast way to add to the current x, y and z values of a vector.

Examples:

Using vector

point1 = Geom::Point3d.new(1, 2, 3)
vector = Geom::Vector3d.new(4, 5, 6)
point2 = point1 + vector

Using array

point1 = Geom::Point3d.new(1, 2, 3)
point2 = point1 + [10,10,10]

Using point

point1 = Geom::Point3d.new(1, 2, 3)
point2 = Geom::Point3d.new(4, 5, 6)
# This works because SketchUp treats the array of triple numerics as
# a vector in this case.
point3 = point1 + point2.to_a

Parameters:

Version:

  • SketchUp 6.0

#-(point2) ⇒ Geom::Vector3d

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]

Parameters:

  • point2 (Point3d) —

    A Point3d object.

Version:

  • SketchUp 6.0

#<(point2) ⇒ Boolean

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

Parameters:

  • point2 (Point3d) —

    A Point3d object.

Returns:

  • (Boolean) —

    true if the point2 is closer to the origin.

Version:

  • SketchUp 6.0

#==(point2) ⇒ Boolean

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

Parameters:

  • point2 (Point3d) —

    A Point3d object.

Returns:

  • (Boolean) —

    true if both points are equal; false if points are not equal

Version:

  • SketchUp 6.0

#[](index) ⇒ Length

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]

Parameters:

  • index (Integer) —

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

Returns:

  • (Length) —

    an x, y, or z value if successful

Version:

  • SketchUp 6.0

#[]=(index, new_value) ⇒ Numeric

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

Parameters:

  • index (Integer) —

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

  • new_value (Numeric) —

    New x, y, or z value.

Returns:

  • (Numeric) —

    the newly set x, y, or z value if successful

Version:

  • SketchUp 6.0

#clone ⇒ Point3d

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:

  • (Point3d) —

    the cloned Point3d object

Version:

  • SketchUp 6.0

#distance(point2) ⇒ Length

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)

Parameters:

  • point2 (Point3d) —

    The Point3d object to compute the distance to.

Version:

  • SketchUp 6.0

#distance_to_line(line) ⇒ Float

Note:

This function returns a ‘Float` value, not a ::Length.

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)

Parameters:

  • line —

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

Returns:

  • (Float) —

    the distance between a point and line in internal units if successful

Version:

  • SketchUp 6.0

#distance_to_plane(plane) ⇒ Float

Note:

This function returns a ‘Float` value, not a ::Length.

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)

Parameters:

  • plane —

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

Returns:

  • (Float) —

    a distance between a point and a plane in internal units if successful

Version:

  • SketchUp 6.0

#inspect ⇒ String

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:

  • (String) —

    a string point representation

Version:

  • SketchUp 6.0

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

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)

Parameters:

  • vector (Geom::Vector3d) —

    A Vector3d object to offset the point by.

  • length (Numeric) (defaults to: vector.length) —

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

Returns:

  • (Point3d) —

    • a new Point3d object

Version:

  • SketchUp 6.0

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

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)

Parameters:

  • vector (Geom::Vector3d) —

    A Vector3d object to offset the point by.

  • length (Numeric) (defaults to: vector.length) —

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

Returns:

  • (Point3d) —

    a new Point3d object

Version:

  • SketchUp 6.0

#on_line?(line) ⇒ Boolean

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)

Parameters:

  • line —

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

Version:

  • SketchUp 6.0

#on_plane?(plane) ⇒ Boolean

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)

Parameters:

  • plane

Version:

  • SketchUp 6.0

#project_to_line(line) ⇒ Point3d

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)

Parameters:

  • line —

    see ::Geom for how to specify a line

Returns:

  • (Point3d) —

    the Point3d that is on a line closest to the point

Version:

  • SketchUp 6.0

#project_to_plane(plane) ⇒ Point3d

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)

Parameters:

  • plane —

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

Returns:

  • (Point3d) —

    the Point3d that is on a plane closest to the point

Version:

  • SketchUp 6.0

#set!(x, y, z) ⇒ Point3d #set!(array3d) ⇒ Point3d #set!(point3d) ⇒ Point3d

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)

Overloads:

  • #set!(x, y, z) ⇒ Point3d

    Parameters:

    • x (Numeric) —

      The x value for the point.

    • y (Numeric) —

      The y value for the point.

    • z (Numeric) —

      The z value for the point.

    Returns:

    • (Point3d) —

      The newly set Point3d object

  • #set!(array3d) ⇒ Point3d

    Parameters:

  • #set!(point3d) ⇒ Point3d

    Parameters:

    • point3d (Point3d)

Version:

  • SketchUp 6.0

#to_a ⇒ Array(Length, Length, Length)

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:

Version:

  • SketchUp 6.0

#to_s ⇒ String

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) ⇒ Point3d

Apply a Transformation to a point, returning a new point. The original vector is unchanged by this method.

Examples:

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

Parameters:

Returns:

  • (Point3d) —

    the newly transformed point

Version:

  • SketchUp 6.0

#transform!(transform) ⇒ Point3d

Apply a Transformation to a point. 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)

Parameters:

Returns:

  • (Point3d) —

    the transformed point

Version:

  • SketchUp 6.0

#vector_to(point2) ⇒ Geom::Vector3d

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)

Parameters:

  • point2 (Point3d) —

    A Point3d object.

Returns:

Version:

  • SketchUp 6.0