Class: Geom::Transformation

Inherits:
Object
  • Object
show all
Defined in:
SketchUp/Geom/Transformation.rb

Overview

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

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Geom::Transformation #initialize(point) ⇒ Geom::Transformation #initialize(vector) ⇒ Geom::Transformation #initialize(transform) ⇒ Geom::Transformation #initialize(array) ⇒ Geom::Transformation #initialize(scale) ⇒ Geom::Transformation #initialize(origin, zaxis) ⇒ Geom::Transformation #initialize(origin, xaxis, yaxis) ⇒ Geom::Transformation #initialize(pt, axis, angle) ⇒ Geom::Transformation #initialize(xaxis, yaxis, zaxis, origin) ⇒ Geom::Transformation

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.

Examples:

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

Overloads:

Version:

  • SketchUp 6.0



345
346
 
# File 'SketchUp/Geom/Transformation.rb', line 345

def initialize(*args)
end

Class Method Details

.axes(origin, xaxis, yaxis, zaxis) ⇒ Geom::Transformation .axes(origin, xaxis, yaxis) ⇒ Geom::Transformation

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

Examples:

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

Overloads:

Raises:

  • (ArgumentError) —

    if any of the vectors are zero length.

Version:

  • SketchUp 6.0



49
50
 
# File 'SketchUp/Geom/Transformation.rb', line 49

def self.axes(*args)
end

.interpolate(transform1, transform2, weight) ⇒ Geom::Transformation

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.

Examples:

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)

Parameters:

Returns:

Version:

  • SketchUp 6.0



79
80
 
# File 'SketchUp/Geom/Transformation.rb', line 79

def self.interpolate(transform1, transform2, weight)
end

.rotation(point, vector, angle) ⇒ Geom::Transformation

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.

Examples:

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)

Parameters:

Returns:

Version:

  • SketchUp 6.0



103
104
 
# File 'SketchUp/Geom/Transformation.rb', line 103

def self.rotation(point, vector, angle)
end

.scaling(scale) ⇒ Geom::Transformation .scaling(xscale, yscale, zscale) ⇒ Geom::Transformation .scaling(point, scale) ⇒ Geom::Transformation .scaling(point, xscale, yscale, zscale) ⇒ Geom::Transformation

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

Examples:

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

Overloads:

  • .scaling(scale) ⇒ Geom::Transformation
    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.

    Parameters:

    • scale (Float) —

      The global scale factor for the transform.

    Returns:

  • .scaling(xscale, yscale, zscale) ⇒ Geom::Transformation

    With three arguments, it does a non-uniform scale about the origin.

    Parameters:

    • xscale (Float) —

      The scale factor in the x direction for the transform.

    • yscale (Float) —

      The scale factor in the y direction for the transform.

    • zscale (Float) —

      The scale factor in the z direction for the transform.

    Returns:

  • .scaling(point, scale) ⇒ Geom::Transformation

    With two arguments, it does a uniform scale about an arbitrary point.

    Parameters:

    • point (Geom::Point3d)
    • scale (Float) —

      The global scale factor for the transform.

    Returns:

  • .scaling(point, xscale, yscale, zscale) ⇒ Geom::Transformation

    With four arguments it does a non-uniform scale about an arbitrary point.

    Parameters:

    • point (Geom::Point3d)
    • xscale (Float) —

      The scale factor in the x direction for the transform.

    • yscale (Float) —

      The scale factor in the y direction for the transform.

    • zscale (Float) —

      The scale factor in the z direction for the transform.

    Returns:

Version:

  • SketchUp 6.0



149
150
 
# File 'SketchUp/Geom/Transformation.rb', line 149

def self.scaling(*args)
end

.translation(vector) ⇒ Geom::Transformation .translation(point) ⇒ Geom::Transformation

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

Examples:

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

Overloads:

Version:

  • SketchUp 6.0



170
171
 
# File 'SketchUp/Geom/Transformation.rb', line 170

def self.translation(arg)
end

Instance Method Details

#*(point) ⇒ Geom::Point3d #*(vector) ⇒ Geom::Vector3d #*(transformation) ⇒ Geom::Transformation #*(point) ⇒ Array<Float, Float, Float> #*(plane) ⇒ Array<Float, Float, Float, Float> #*(plane) ⇒ Array<Float, Float, Float, Float>

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

Examples:

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

Overloads:

Version:

  • SketchUp 6.0



215
216
 
# File 'SketchUp/Geom/Transformation.rb', line 215

def *(arg)
end

#clone ⇒ Geom::Transformation

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0



228
229
 
# File 'SketchUp/Geom/Transformation.rb', line 228

def clone
end

#identity? ⇒ Boolean

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.

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

Examples:

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

Returns:

  • (Boolean) —

    true if the transformation is the identity

  • (Boolean)

Version:

  • SketchUp 6.0



264
265
 
# File 'SketchUp/Geom/Transformation.rb', line 264

def identity?
end

#inverse ⇒ Geom::Transformation

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0



358
359
 
# File 'SketchUp/Geom/Transformation.rb', line 358

def inverse
end

#invert! ⇒ Geom::Transformation

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0



371
372
 
# File 'SketchUp/Geom/Transformation.rb', line 371

def invert!
end

#origin ⇒ Geom::Point3d

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0



384
385
 
# File 'SketchUp/Geom/Transformation.rb', line 384

def origin
end

#set!(transformation) ⇒ Geom::Transformation #set!(point) ⇒ Geom::Transformation #set!(vector) ⇒ Geom::Transformation #set!(matrix) ⇒ Geom::Transformation #set!(scale) ⇒ Geom::Transformation

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

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

Examples:

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

Overloads:

Version:

  • SketchUp 6.0



423
424
 
# File 'SketchUp/Geom/Transformation.rb', line 423

def set!(arg)
end

#to_a ⇒ Array<Float>

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0



438
439
 
# File 'SketchUp/Geom/Transformation.rb', line 438

def to_a
end

#xaxis ⇒ Geom::Vector3d

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0



451
452
 
# File 'SketchUp/Geom/Transformation.rb', line 451

def xaxis
end

#yaxis ⇒ Geom::Vector3d

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0



464
465
 
# File 'SketchUp/Geom/Transformation.rb', line 464

def yaxis
end

#zaxis ⇒ Geom::Vector3d

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

Examples:

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

Returns:

Version:

  • SketchUp 6.0



477
478
 
# File 'SketchUp/Geom/Transformation.rb', line 477

def zaxis
end