# Class: Geom::Transformation

Inherits:
Object
• Object
show all

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

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

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

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

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

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

## Instance Method Summary collapse

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

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

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

• constructor

The new method is used to create a new transformation.

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

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

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

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

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

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

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

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

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

• #initializeGeom::Transformation

Returns identity Transformation.

• #initialize(point) ⇒ Geom::Transformation

Translates the origin to point.

Parameters:

• point
• #initialize(vector) ⇒ Geom::Transformation

Parameters:

• vector
• #initialize(transform) ⇒ Geom::Transformation

Creates a Transformation that is a copy of another Transformation. This is equivalent to #clone.

Parameters:

• transform
• #initialize(array) ⇒ Geom::Transformation

Parameters:

• Creates (Array<Float>)

a Transformation from a 16 element Array.

• #initialize(scale) ⇒ Geom::Transformation

Creates a transformation that does uniform scaling.

Parameters:

• scale (Float)
• #initialize(origin, zaxis) ⇒ Geom::Transformation

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.

Parameters:

• origin
• zaxis
• #initialize(origin, xaxis, yaxis) ⇒ Geom::Transformation

Creates a Transformation given a new origin, x axis and y axis.

Parameters:

• origin
• xaxis
• yaxis
• #initialize(pt, axis, angle) ⇒ Geom::Transformation

Creates a Transformation that rotates by angle (given in radians) about a line defined by pt and axis.

Parameters:

• origin
• axis
• angle (Float)
• #initialize(xaxis, yaxis, zaxis, origin) ⇒ Geom::Transformation

Parameters:

• xaxis
• yaxis
• zaxis
• origin

Version:

• SketchUp 6.0

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

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

Parameters:

• origin
• xaxis
• yaxis
• zaxis

Returns:

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

When the Z axis is omitted and arbitrary axis is computed from the X and Y axes.

Parameters:

• origin
• xaxis
• yaxis

Returns:

Raises:

• (ArgumentError)

if any of the vectors are zero length.

Version:

• SketchUp 6.0

### .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:

• transform1
• transform2
• weight (Float)

A value between 0.0 and 1.0 (see comments).

Returns:

Version:

• SketchUp 6.0

### .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:

• point
• vector
• angle (Float)

Returns:

Version:

• SketchUp 6.0

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

• .scaling(scale) ⇒ Geom::Transformation
Note:

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

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

Version:

• SketchUp 6.0

## Instance Method Details

### #*(point) ⇒ Geom::Point3d #*(vector) ⇒ Geom::Vector3d #*(transformation) ⇒ Geom::Transformation #*(point) ⇒ Geom::Point3d #*(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``````

• #*(point) ⇒ Geom::Point3d

Parameters:

• point

Returns:

• #*(vector) ⇒ Geom::Vector3d

Parameters:

• vector

Returns:

• #*(transformation) ⇒ Geom::Transformation

Parameters:

• transformation

Returns:

• #*(point) ⇒ Geom::Point3d

Parameters:

• point (Array<Float, Float, Float>)

Returns:

• #*(plane) ⇒ Array<Float, Float, Float, Float>

Returns transformed plane

Parameters:

• plane

Returns:

• (Array<Float, Float, Float, Float>)

transformed plane

• #*(plane) ⇒ Array<Float, Float, Float, Float>

Returns transformed plane

Parameters:

• plane (Array<Float, Float, Float, Float>)

Returns:

• (Array<Float, Float, Float, Float>)

transformed plane

Version:

• SketchUp 6.0

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

### #identity? ⇒ Boolean

Note:

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

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

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

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

• the origin of the transformation.

Version:

• SketchUp 6.0

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

Version:

• SketchUp 6.0

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

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

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

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