Transformation

The SketchUp JavaScript API is currently a labs feature.
Signup as a developer and try it out.

A 4x4 matrix describing a position, rotation, and scale in 3D space.

Transformations are how you move, rotate, and scale geometry in SketchUp. Every group and component instance carries a transformation that positions it in the model.

You usually don’t construct these directly — instead, call the static factory methods translation(), rotation(), or scaling(), then pass the result to operation methods like drawingElementsApplyTransformation.

Transformations are immutable. Methods like applyTo() and inverse return new instances.

Example

let model = await SketchUpApi.getActiveModel();
let { Transformation } = SketchUpApi;

await model.performOperation(async op => {
  const groupRef = op.createGroup(model);
  op.createEdge(groupRef, [[0,0,0], [50,0,0]]);

  // Move the group 20" along the green axis
  op.drawingElementsApplyTransformation(
    groupRef, Transformation.translation([0, 20, 0])
  );
}, 'Create and move group');

// Compose transformations with applyTo
let move = Transformation.translation([10, 0, 0]);
let spin = Transformation.rotation(
  [0, 0, 0], [0, 0, 1], Math.PI / 4
);
let combined = move.applyTo(spin);
console.log(combined.origin.toArray());
// => [10, 0, 0]

See

• TransformationLike
• Operation.drawingElementsApplyTransformation
• Transformation.fromArray

Constructor

Constructor

new Transformation(_m?): Transformation

Creates a Transformation directly from a raw 16-element column-major matrix array — equivalent to fromArray(). Most code should prefer the static factory methods or fromArray() for clarity; this is here for advanced cases where you already have a raw matrix on hand.

Parameters

Parameter	Type	Default value	Description
_m	readonly [number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number]	Transformation.IDENTITY	16 numbers in column-major order. Defaults to the identity matrix.

Returns

Transformation

Properties

identity

readonly static identity: Transformation

The identity transformation (no translation, rotation, or scale). Use this as a starting point or default value.

Example

let { Transformation } = SketchUpApi;

// This is the static property — it returns
// the identity Transformation instance.
let t = Transformation.identity;
console.log(t.origin.toArray());
// => [0, 0, 0]

Accessors

identity

Get Signature

get identity(): boolean

True if this transformation has no effect (no translation, rotation, or scale). Not to be confused with the static Transformation.identity property which returns the identity instance itself.

Example

let { Transformation } = SketchUpApi;

// This is the getter — it returns a boolean
// telling you if a transform is a no-op.
let move = Transformation.translation([10, 0, 0]);
console.log(move.identity);
// => false (it moves things!)
console.log(Transformation.identity.identity);
// => true (yes, identity is identity)

Returns

boolean

---

inverse

Get Signature

get inverse(): Transformation

A new transformation that undoes this one. Applying a transformation followed by its inverse returns to the original position.

Returns

Transformation

---

origin

Get Signature

get origin(): Point3d

The translation component of this transformation — where the local origin ends up in world space.

Returns

Point3d

---

xaxis

Get Signature

get xaxis(): Vector3d

The local X axis direction after this transformation is applied (the “red axis” of the transformed space).

Returns

Vector3d

---

yaxis

Get Signature

get yaxis(): Vector3d

The local Y axis direction after this transformation is applied (the “green axis” of the transformed space).

Returns

Vector3d

---

zaxis

Get Signature

get zaxis(): Vector3d

The local Z axis direction after this transformation is applied (the “blue axis” of the transformed space).

Returns

Vector3d

Methods

applyTo()

Call Signature

applyTo(point): Point3d

Applies this transformation to a point, vector, plane, or another transformation. Returns a new transformed instance — the original is unchanged. When applied to another transformation, the result is their composition (matrix multiplication).

Parameters

Parameter	Type	Description
point	Point3d	‐

Returns

Point3d

Call Signature

applyTo(vector): Vector3d

Applies this transformation to a point, vector, plane, or another transformation. Returns a new transformed instance — the original is unchanged. When applied to another transformation, the result is their composition (matrix multiplication).

Parameters

Parameter	Type
vector	Vector3d

Returns

Vector3d

Call Signature

applyTo(transformation): Transformation

Applies this transformation to a point, vector, plane, or another transformation. Returns a new transformed instance — the original is unchanged. When applied to another transformation, the result is their composition (matrix multiplication).

Parameters

Parameter	Type
transformation	Transformation

Returns

Transformation

Call Signature

applyTo(point): Point3d

Applies this transformation to a point, vector, plane, or another transformation. Returns a new transformed instance — the original is unchanged. When applied to another transformation, the result is their composition (matrix multiplication).

Parameters

Parameter	Type	Description
point	[number, number, number]	‐

Returns

Point3d

Call Signature

applyTo(plane): Plane

Applies this transformation to a point, vector, plane, or another transformation. Returns a new transformed instance — the original is unchanged. When applied to another transformation, the result is their composition (matrix multiplication).

Parameters

Parameter	Type
plane	[number, number, number, number]

Returns

Plane

Call Signature

applyTo(plane): Plane

Applies this transformation to a point, vector, plane, or another transformation. Returns a new transformed instance — the original is unchanged. When applied to another transformation, the result is their composition (matrix multiplication).

Parameters

Parameter	Type
plane	[Point3d, Vector3d]

Returns

Plane

Call Signature

applyTo(plane): Plane

Applies this transformation to a point, vector, plane, or another transformation. Returns a new transformed instance — the original is unchanged. When applied to another transformation, the result is their composition (matrix multiplication).

Parameters

Parameter	Type
plane	Plane

Returns

Plane

---

toArray()

toArray(): SketchupTransform

Returns the 16-element column-major matrix as an array.

Returns

SketchupTransform

Since

SDK 2.35.0

---

toString()

toString(): string

Returns

string

---

axes()

static axes(origin, xaxis, yaxis, zaxis?): Transformation

Creates a transformation that maps world coordinates into a local coordinate system defined by an origin and axis vectors.

Parameters

Parameter	Type	Default value	Description
origin	Point3d	undefined	‐
xaxis	Vector3d	undefined	‐
yaxis	Vector3d	undefined	‐
zaxis	Vector3d | undefined	undefined	optional — computed from x cross y if omitted

Returns

Transformation

---

create()

static create(transform): Transformation

Utility that constructs a transform from anything shaped like a transformation

Parameters

Parameter	Type
transform	Readonly<TransformationLike>

Returns

Transformation

Example

let translations = SketchUpApi.Transformation.create([100, 200, 300]);

Since

SDK 2.37.0

---

fromArray()

static fromArray(array): Transformation

Creates a Transformation from a 16-element column-major matrix array — the inverse of to_a.

Parameters

Parameter	Type	Description
array	readonly number[]	16 numbers in column-major order

Returns

Transformation

---

interpolate()

static interpolate(transform1, transform2, weight): Transformation

Blends between two transformations. A weight of 0 returns transform1, 1 returns transform2, and values in between produce a smooth interpolation (slerp for rotation, lerp for translation).

Parameters

Parameter	Type	Description
transform1	Transformation	‐
transform2	Transformation	‐
weight	number	0–1 blend factor

Returns

Transformation

---

originAndDirection()

static originAndDirection(origin, direction): Transformation

Creates a transformation whose Z axis points along direction, with an arbitrary but consistent X and Y axis computed perpendicular to it. Useful when you only care about orientation along one axis — like aligning geometry to a face normal — and don’t need to specify all three axes yourself. See Transformation.axes if you do.

Parameters

Parameter	Type	Description
origin	Point3Like	the transformation’s origin
direction	Vector3Like	becomes the new Z axis

Returns

Transformation

Example

let { Transformation } = SketchUpApi;

// Orient a transform along an arbitrary direction
let t = Transformation.originAndDirection(
  [0, 0, 0], [0, 0, 1]
);
console.log(t.zaxis.toArray());
// => [0, 0, 1]

---

rotation()

static rotation(point, vector, angle): Transformation

Creates a rotation transformation around an axis passing through a point. The angle is in radians — multiply degrees by Math.PI / 180 to convert.

Parameters

Parameter	Type	Description
point	Point3Like	center of rotation
vector	Vector3Like	axis direction
angle	number	rotation amount in radians

Returns

Transformation

Example

let model = await SketchUpApi.getActiveModel();
let { Transformation } = SketchUpApi;

await model.performOperation(async op => {
  const groupRef = op.createGroup(model);
  op.createFace(groupRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);

  // Rotate 45° about the Z axis at the origin
  const degrees = 45;
  const radians = degrees * Math.PI / 180;
  op.drawingElementsApplyTransformation(
    groupRef,
    Transformation.rotation(
      [0, 0, 0], [0, 0, 1], radians
    )
  );
}, 'Rotated square');

---

scaling()

Call Signature

static scaling(scale): Transformation

Creates a scaling transformation. Pass a single number for uniform scale, three numbers for per-axis scale, or include a point to scale around a specific origin.

Parameters

Parameter	Type	Description
scale	number	‐

Returns

Transformation

Call Signature

static scaling(xscale, yscale, zscale): Transformation

Creates a scaling transformation. Pass a single number for uniform scale, three numbers for per-axis scale, or include a point to scale around a specific origin.

Parameters

Parameter	Type
xscale	number
yscale	number
zscale	number

Returns

Transformation

Call Signature

static scaling(point, scale): Transformation

Creates a scaling transformation. Pass a single number for uniform scale, three numbers for per-axis scale, or include a point to scale around a specific origin.

Parameters

Parameter	Type	Description
point	Point3d	‐
scale	number	‐

Returns

Transformation

Call Signature

static scaling(point, xscale, yscale, zscale): Transformation

Creates a scaling transformation. Pass a single number for uniform scale, three numbers for per-axis scale, or include a point to scale around a specific origin.

Parameters

Parameter	Type
point	Point3d
xscale	number
yscale	number
zscale	number

Returns

Transformation

---

translation()

static translation(arg): Transformation

Creates a translation (move) transformation.

Parameters

Parameter	Type	Description
arg	Readonly<Vector3d | [number, number, number] | [number, number] | { x: number; y: number; z?: number; } | Point3d | { x: number; y: number; z?: number; }>	offset as a Vector3d, Point3d, or [x, y, z]

Returns

Transformation

Example

let model = await SketchUpApi.getActiveModel();
let { Transformation } = SketchUpApi;

await model.performOperation(async op => {
  const groupRef = op.createGroup(model);
  op.createFace(groupRef, [
    [0, 0, 0], [30, 0, 0],
    [30, 30, 0], [0, 30, 0]
  ]);

  // Move the group 50" along the red axis
  op.drawingElementsApplyTransformation(
    groupRef, Transformation.translation([50, 0, 0])
  );
}, 'Translated square');

Show Deprecated

Deprecated

to_a

Get Signature

get to_a(): SketchupTransform

Deprecated

since SDK 2.35.0, use toArray() instead.

Returns

SketchupTransform