class Geom::Transformation

Transformations are a standard construct in the 3D world for representing the position, rotation, and sizing of a given entity. In the SketchUp world, {Sketchup::ComponentInstance} and {Sketchup::Group} have a .transformation method that reports their current state and various methods (.move!, transformation=, etc.) that allow them to be manipulated.

Use of the transformation class requires a knowledge of geometrical transformations in 3 dimensions which is covered extensively on the Internet.

@version SketchUp 6.0

Public Class Methods

axes(*args) click to toggle source

The axes method creates a transformation that goes from world coordinates to an arbitrary coordinate system defined by an origin and three axis vectors.

@example

# Creates a transformation that "flips" the axes from XYZ to XZY. Something
# one often need for importers/exporters when dealing with applications
# that threat Y as "up".
tr = Geom::Transformation.axes(ORIGIN, X_AXIS, Z_AXIS, Y_AXIS.reverse)

@overload axes(origin, xaxis, yaxis, zaxis)

@param [Geom::Point3d] origin
@param [Geom::Vector3d] xaxis
@param [Geom::Vector3d] yaxis
@param [Geom::Vector3d] zaxis
@return [Geom::Transformation]

@overload axes(origin, xaxis, yaxis)

When the Z axis is omitted and arbitrary axis is computed from the X and Y
axes.
@param [Geom::Point3d] origin
@param [Geom::Vector3d] xaxis
@param [Geom::Vector3d] yaxis
@return [Geom::Transformation]

@raise [ArgumentError] if any of the vectors are zero length.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 49
def self.axes(*args)
end
interpolate(transform1, transform2, weight) click to toggle source

The interpolate method is used to create a new transformation that is the result of interpolating between two other transformations.

Parameter is a weight (between 0.0 and 1.0) that identifies whether to favor transformation1 or transformation2.

@example

origin = Geom::Point3d.new(0, 0, 0)
x = Geom::Vector3d.new(0, 1, 0)
y = Geom::Vector3d.new(1, 0, 0)
z = Geom::Vector3d.new(0, 0, 1)
point = Geom::Point3d.new(10, 20, 30)
t1 = Geom::Transformation.new(point)
t2 = Geom::Transformation.axes(origin, x, y, z)
# This produce a transformation that is a mix of 75% t1 and 25% t2.
t3 = Geom::Transformation.interpolate(t1, t2, 0.25)

@param [Geom::Transformation] transform1

@param [Geom::Transformation] transform2

@param [Float] weight

A value between 0.0 and 1.0 (see comments).

@return [Geom::Transformation]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 79
def self.interpolate(transform1, transform2, weight)
end
new(*args) click to toggle source

The new method is used to create a new transformation.

You can use this method or one of the more specific methods for creating specific kinds of Transformations.

@example

point = Geom::Point3d.new(10, 20, 30)
tr = Geom::Transformation.new(point)

@overload initialize

@return [Geom::Transformation] identity Transformation.

@overload initialize(point)

Translates the origin to point.
@param [Geom::Point3d] point
@return [Geom::Transformation]

@overload initialize(vector)

@param [Geom::Vector3d] vector
@return [Geom::Transformation]

@overload initialize(transform)

Creates a Transformation that is a copy of another Transformation. This is
equivalent to {#clone}.
@param [Geom::Transformation] transform
@return [Geom::Transformation]

@overload initialize(array)

@param [Array<Float>] Creates a Transformation from a 16 element Array.
@return [Geom::Transformation]

@overload initialize(scale)

Creates a transformation that does uniform scaling.
@note Versions prior to SU2018 would produce transformations which
  didn't always work right in SketchUp. See {.scaling} for more info.
@param [Float] scale
@return [Geom::Transformation]

@overload initialize(origin, zaxis)

Creates a Transformation where origin is the new origin, and zaxis is the
z axis. The x and y axes are determined using an arbitrary axis rule.
@param [Geom::Point3d] origin
@param [Geom::Vector3d] zaxis
@return [Geom::Transformation]

@overload initialize(origin, xaxis, yaxis)

Creates a Transformation given a new origin, x axis and y axis.
@param [Geom::Point3d] origin
@param [Geom::Vector3d] xaxis
@param [Geom::Vector3d] yaxis
@return [Geom::Transformation]

@overload initialize(pt, axis, angle)

Creates a Transformation that rotates by angle (given in radians) about a
line defined by pt and axis.
@param [Geom::Point3d] origin
@param [Geom::Vector3d] axis
@param [Float] angle
@return [Geom::Transformation]

@overload initialize(xaxis, yaxis, zaxis, origin)

@param [Geom::Vector3d] xaxis
@param [Geom::Vector3d] yaxis
@param [Geom::Vector3d] zaxis
@param [Geom::Point3d] origin
@return [Geom::Transformation]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 343
def initialize(*args)
end
rotation(point, vector, angle) click to toggle source

The rotation method is used to create a transformation that does rotation about an axis.

The axis is defined by a point and a vector. The angle is given in radians.

@example

point = Geom::Point3d.new(10, 20, 0)
vector = Geom::Vector3d.new(0, 0, 1)
angle = 45.degrees # Return 45 degrees in radians.
transformation = Geom::Transformation.rotation(point, vector, angle)

@param [Geom::Point3d] point

@param [Geom::Vector3d] vector

@param [Float] angle

The angle in radians.

@return [Geom::Transformation]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 103
def self.rotation(point, vector, angle)
end
scaling(*args) click to toggle source

The scaling method is used to create a transformation that does scaling.

@example

point = Geom::Point3d.new(20, 30, 0)
scale = 10
tr = Geom::Transformation.scaling(point, scale)

@overload scaling(scale)

@note This has been fixed in SketchUp 2018 but in previous versions it
  might yield an unexpected transformation. It sets the 16th value
  to the scaling factor. Something not all extensions reading the
  transformation expects. Consider using +scaling(xscale, yscale, zscale)+
  instead.
With one argument, it does a uniform scale about the origin.
@param [Float] scale  The global scale factor for the transform.
@return [Geom::Transformation]

@overload scaling(xscale, yscale, zscale)

With three arguments, it does a non-uniform scale about the origin.
@param [Float] xscale  The scale factor in the x direction for the transform.
@param [Float] yscale  The scale factor in the y direction for the transform.
@param [Float] zscale  The scale factor in the z direction for the transform.
@return [Geom::Transformation]

@overload scaling(point, scale)

With two arguments, it does a uniform scale about an arbitrary point.
@param [Geom::Point3d] point
@param [Float] scale  The global scale factor for the transform.
@return [Geom::Transformation]

@overload scaling(point, xscale, yscale, zscale)

With four arguments it does a non-uniform scale about an arbitrary point.
@param [Geom::Point3d] point
@param [Float] xscale  The scale factor in the x direction for the transform.
@param [Float] yscale  The scale factor in the y direction for the transform.
@param [Float] zscale  The scale factor in the z direction for the transform.
@return [Geom::Transformation]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 149
def self.scaling(*args)
end
translation(arg) click to toggle source

The translation method is used to create a transformation that does translation.

@example

vector = Geom::Vector3d.new(0, 1, 0)
tr = Geom::Transformation.translation(vector)

@overload translation(vector)

@param [Geom::Vector3d] vector
@return [Geom::Transformation]

@overload translation(point)

@param [Geom::Point3d] point
@return [Geom::Transformation]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 170
def self.translation(arg)
end

Public Instance Methods

*(arg) click to toggle source

The {#*} method is used to do matrix multiplication using the transform.

@example

point1 = Geom::Point3d.new(10, 20, 30)
point2 = Geom::Point3d.new(2, 2, 2)
tr = Geom::Transformation.new(point1)
# Returns Point3d(12, 22, 32)
point3 = tr * point2

@overload *(point)

@param [Geom::Point3d] point
@return [Geom::Point3d]

@overload *(vector)

@param [Geom::Vector3d] vector
@return [Geom::Vector3d]

@overload *(transformation)

@param [Geom::Transformation] transformation
@return [Geom::Transformation]

@overload *(point)

@param [Array<Float, Float, Float>] point
@return [Array<Float, Float, Float>]

@overload *(plane)

@param [Array<Geom::Point3d, Geom::Vector3d>] plane
@return [Array<Float, Float, Float, Float>] transformed plane

@overload *(plane)

@param [Array<Float, Float, Float, Float>] plane
@return [Array<Float, Float, Float, Float>] transformed plane

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 215
def *(arg)
end
clone() click to toggle source

The {#clone} method is used to create a copy of a transformation.

@example

point = Geom::Point3d.new(10, 20, 30)
tr1 = Geom::Transformation.new(point)
tr2 = tr1.clone

@return [Geom::Transformation]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 228
def clone
end
identity?() click to toggle source

The {#identity?} method is used to determine if a transformation is the {IDENTITY} transform.

@example

point = Geom::Point3d.new(10, 20, 30)
tr = Geom::Transformation.new(point)
# Returns false.
status = tr.identity?

@example

tr = Geom::Transformation.new(ORIGIN)
# Returns false.
status = tr.identity?

@example

tr = Geom::Transformation.new
# Returns true.
status = tr.identity?

@example

# Returns true.
status = IDENTITY.identity?

@note As of SketchUp 2018, this now looks at the data to determine if the

transformation is identity. Prior to SU2018, this only looks at the flag to
see if the transform has not been modified. If the transform has been
changed, this will return false even if it is really the identity.

@return [Boolean] true if the transformation is the identity

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 262
def identity?
end
inverse() click to toggle source

The {#inverse} method is used to retrieve the inverse of a transformation.

@example

point = Geom::Point3d.new(10, 20, 30)
tr1 = Geom::Transformation.new(point)
tr2 = tr1.inverse

@return [Geom::Transformation]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 356
def inverse
end
invert!() click to toggle source

The {#invert!} method sets the transformation to its inverse.

@example

point = Geom::Point3d.new(10, 20, 30)
tr = Geom::Transformation.new(point)
tr.invert!

@return [Geom::Transformation]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 369
def invert!
end
origin() click to toggle source

The {#origin} method retrieves the origin of a rigid transformation.

@example

point1 = Geom::Point3d.new(10, 20, 30)
tr = Geom::Transformation.new(point1)
point2 = tr.origin

@return [Geom::Point3d] the origin of the transformation.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 382
def origin
end
set!(arg) click to toggle source

The {#set!} method is used to set this transformation to match another one.

The argument is anything that can be converted into a transformation.

@example

point1 = Geom::Point3d.new(10, 20, 30)
tr1 = Geom::Transformation.new(point)
point2 = Geom::Point3d.new(60, 40, 70)
tr1.set!(point2)

@overload set!(transformation)

@param [Geom::Transformation] transformation
@return [Geom::Transformation]

@overload set!(point)

@param [Geom::Point3d] point
@return [Geom::Transformation]

@overload set!(vector)

@param [Geom::Vector3d] vector
@return [Geom::Transformation]

@overload set!(matrix)

@param [Array<Float>] matrix  Array of 16 floats.
@return [Geom::Transformation]

@overload set!(scale)

@param [Float] scale
@return [Geom::Transformation]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 421
def set!(arg)
end
to_a() click to toggle source

The {#to_a} method retrieves a 16 element array which contains the values that define the transformation.

@example

point = Geom::Point3d.new(10, 20, 30)
tr = Geom::Transformation.new(point)
# This splits the 16 items into a string of 4x4 elements for easier reading.
str4x4 = tr.to_a.each_slice(4).inject { |str, row| "#{str}\r\n#{row}" }

@return [Array<Float>]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 436
def to_a
end
xaxis() click to toggle source

The {#xaxis} method retrieves the x axis of a rigid transformation.

@example

point = Geom::Point3d.new(10, 20, 30)
tr = Geom::Transformation.new(point)
x = tr.xaxis

@return [Geom::Vector3d]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 449
def xaxis
end
yaxis() click to toggle source

The {#yaxis} method retrieves the y axis of a rigid transformation.

@example

point = Geom::Point3d.new(10, 20, 30)
tr = Geom::Transformation.new(point)
x = tr.yaxis

@return [Geom::Vector3d]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 462
def yaxis
end
zaxis() click to toggle source

The {#zaxis} method retrieves the z axis of a rigid transformation.

@example

point = Geom::Point3d.new(10, 20, 30)
tr = Geom::Transformation.new(point)
x = tr.zaxis

@return [Geom::Vector3d]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Geom/Transformation.rb, line 475
def zaxis
end