Vector3d

A direction and magnitude in 3D space.

Vectors describe displacements, normals, and directions. Unlike Point3d (which is a position), a vector has no fixed location — it represents “how far and which way.” Vectors are immutable: operations like add(), cross(), and normalize return new instances.

Common uses include rotation axes, face normals, translation offsets, and computing angles between directions.

Example

let { Vector3d } = SketchUpApi;

let up = new Vector3d(0, 0, 1);
let diagonal = new Vector3d(1, 1, 0);

// Angle between two vectors (radians)
let angle = up.angleBetween(diagonal);
console.log((angle * 180 / Math.PI).toFixed(1));
// => 90.0

// Cross product gives a perpendicular vector
let perp = up.cross(diagonal);
console.log(perp.normalize.toArray());
// => [-0.707, 0.707, 0] (approx)

// Length and normalization
console.log(diagonal.length.toFixed(3));
// => 1.414
console.log(diagonal.normalize.toArray());
// => [0.707, 0.707, 0] (approx)

See

Constructor

new Vector3d(x?, y?, z?): Vector3d

Parameters

Parameter	Type	Default value
`x`	`number`	`0`
`y`	`number`	`0`
`z`	`number`	`0`

Returns

Vector3d

Properties

x

readonly x: number = 0

y

readonly y: number = 0

z

readonly z: number = 0

Accessors

axes

Get Signature

get axes(): [Vector3d, Vector3d, Vector3d]

Creates an arbitrary axes triple that satisfy this direction as the z-axis direction.

Example

let { Vector3d } = SketchUpApi;
let vector = new Vector(0, 0, 1);
console.log(vector.axes);

Returns

[Vector3d, Vector3d, Vector3d]

an Array of three vectors [xaxis, yaxis, zaxis]

length

Get Signature

get length(): number

The magnitude (length) of this vector.

Example

let { Vector3d } = SketchUpApi;
let vector = new Vector(1, 2, 3);
// 1
console.log(vector.normalize.length);
// √14
console.log(vector.length);

Returns

number

normalize

Get Signature

get normalize(): Vector3d

A unit vector (length 1) pointing in the same direction.

Example

let { Vector3d } = SketchUpApi;
let vector = new Vector(1, 2, 3);
// ~Vector3d(0.267,0.535,0.802)
console.log(vector.normalize.toString());

Returns

Vector3d

reverse

Get Signature

get reverse(): Vector3d

A new vector pointing in the opposite direction (negated components), with the same length.

Returns

Vector3d

Methods

add()

add(vector2): Vector3d

Returns a new vector that is the sum of this vector and another.

Parameters

Parameter	Type	Description
`vector2`	`Readonly`<`Vector3Like`>	‐

Returns

Vector3d

Example

let { Vector3d } = SketchUpApi;
let a = new Vector3d(1, 2, 3);
let b = new Vector3d(10, 20, 30);

// Vector3d(11,22,33);
console.log(a.add(b).toString());

angleBetween()

angleBetween(vector2): number

The angle between this vector and another, in radians (always 0 to PI).

Parameters

Parameter	Type	Description
`vector2`	`Readonly`<`Vector3Like`>	‐

Returns

number

Example

let { Vector3d } = SketchUpApi;
let a = new Vector3d(1, 2, 3);
let b = new Vector3d(1, -2, 3);

// PI / 2
console.log(a.angleBetween(b));

cross()

cross(vector): Vector3d

The cross product of this vector and another — a new vector perpendicular to both, whose length equals the area of the parallelogram they span.

Parameters

Parameter	Type	Description
`vector`	`Readonly`<`Vector3Like`>	‐

Returns

Vector3d

Example

let { Vector3d } = SketchUpApi;
let vector = new Vector(0, 0, 1);
// Vector3d(0,1,0)
console.log(vector.cross([1, 0, 0]).toString());

dot()

dot(vector): number

The dot product of this vector and another. Positive when they point in similar directions, zero when perpendicular, negative when opposing.

Parameters

Parameter	Type	Description
`vector`	`Readonly`<`Vector3Like`>	‐

Returns

number

Example

let { Vector3d } = SketchUpApi;
let vector = new Vector(0, 0, 1);
// 0
console.log(vector.dot([1, 0, 0]));
// √2
console.log(vector.dot([1, 1, 0]));

equalTo()

equalTo(vector2): boolean

Compares two vectors component-wise within a 0.001 tolerance.

let { Vector3d } = SketchUpApi;
let a = new Vector3d(1, 2, 3);

// true
console.log(a.equalTo(a.add([0.0009,0,0])));
// false
console.log(a.equalTo(a.add([0.001,0,0])));

Parameters

Parameter	Type	Description
`vector2`	`Readonly`<`Vector3Like`>	‐

Returns

boolean

isParallel()

isParallel(vector2): boolean

True if this vector is parallel (or anti-parallel) to another, within tolerance.

Parameters

Parameter	Type	Description
`vector2`	`Readonly`<`Vector3Like`>	‐

Returns

boolean

Example

let { Vector3d } = SketchUpApi;
let a = new Vector3d(1, 2, 3);
let b = new Vector3d(11, 22, 33);
let c = new Vector3d(1, -2, 3);
let d = new Vector3d(-1, -2, -3);
// true
console.log(a.isParallel(b));
// false
console.log(a.isParallel(c));
// true
console.log(a.isParallel(d));

isPerpendicular()

isPerpendicular(vector2): boolean

True if this vector is perpendicular to another (dot product is within tolerance of zero).

Parameters

Parameter	Type	Description
`vector2`	`Readonly`<`Vector3Like`>	‐

Returns

boolean

Example

let { Vector3d } = SketchUpApi;
let a = new Vector(1, 2, 3);
let b = new Vector(11, 22, 33);
let c = new Vector(1, -2, 3);
// false
console.log(a.perpendicular(b));
// true
console.log(a.perpendicular(c));

Since

SDK 2.37.0

isSameDirectionAs()

isSameDirectionAs(vector2): boolean

True if this vector points in the same direction as another (within tolerance).

Parameters

Parameter	Type	Description
`vector2`	`Readonly`<`Vector3Like`>	‐

Returns

boolean

Example

let { Vector3d } = SketchUpApi;
let a = new Vector3d(1, 2, 3);
let b = new Vector3d(11, 22, 33);
let c = new Vector3d(1, -2, 3);
let d = new Vector3d(-1, -2, -3);
// true
console.log(a.isSameDirectionAs(b));
// false
console.log(a.isSameDirectionAs(c));
// false
console.log(a.isSameDirectionAs(d));

Since

SDK 2.37.0

isUnitVector()

isUnitVector(): boolean

Returns true if the Vector3d.length is close enough to 1

Returns

boolean

Boolean true if this represents a unit vector

Since

SDK 2.37.0

minus()

minus(vector2): Vector3d

Returns a new vector with the other vector subtracted from this one.

Parameters

Parameter	Type	Description
`vector2`	`Readonly`<`Vector3Like`>	‐

Returns

Vector3d

Example

let { Vector3d } = SketchUpApi;
let a = new Vector3d(1, 2, 3);
let b = new Vector3d(10, 20, 30);

// Vector3d(-9,-18,-27);
console.log(a.minus(b).toString());

scale()

scale(by): Vector3d

Returns a new vector scaled by the given factor.

Parameters

Parameter	Type	Description
`by`	`number`	‐

Returns

Vector3d

Example

let { Vector3d } = SketchUpApi;
let vector = new Vector(1, 2, 3);
// Vector3d(2,4,6)
console.log(vector.scale(2).toString());

toArray()

toArray(): [number, number, number]

Returns this vector as an [x, y, z] tuple.

Returns

[number, number, number]

Since

SDK 2.35.0

toString()

toString(): string

Returns

string

with()

with(partialVector): Vector3d

Returns a new vector with the defined values from the partialPoint replacing this vector.

Null and undefined values are ignored.

Parameters

Parameter	Type	Description
`partialVector`	`Partial`<{ `x`: `number` \| `null`; `y`: `number` \| `null`; `z`: `number` \| `null`; }>	‐

Returns

Vector3d

Example

let { Vector3d } = SketchUpApi;
let a = new Vector3d(1,2,3);
let b = a.with({z: 0});
// Vector3d(1,2,0)
console.log(b.toString());

Since

SDK 2.37.0

create()

static create(input): Vector3d

Utility that creates a Vector3d from an input that is shaped like a Vector3d.

Parameters

Parameter	Type	Description
`input`	`Readonly`<`Vector3Like`>	input that is shaped like a Vector3d

Returns

Vector3d

Example

let { Vector3d } = SketchUpApi;
Vector3d.create({x: 100, y: 200});
Vector3d.create([100, 200]);
Vector3d.create({x: 100, y: 200, z: 300});
Vector3d.create([100, 200, 300]);

Throws

Error an invalid input

Since

SDK 2.37.0

direction()

static direction(eye, target): Vector3d

Creates a vector pointing from one point to another (not normalized — its length is the distance between them).

Parameters

Parameter	Type	Description
`eye`	`Readonly`<`Point3Like`>	starting point
`target`	`Readonly`<`Point3Like`>	ending point

Returns

Vector3d

Example

let { Vector3d } = SketchUpApi;
let vector = Vector3d.direction([1,2,3],[10,20,30]);
// Vector3d(9,18,27)
console.log(vector.toString());

fromLinearCombination()

static fromLinearCombination(w1, v1, w2, v2): Vector3d

Combines two points using weighted coefficients: w1 * p1 + w2 * p2. Commonly used to interpolate between two points — for example, the midpoint is fromLinearCombination(0.5, p1, 0.5, p2) — though the weights don’t need to sum to 1.

Parameters

Parameter	Type	Description
`w1`	`number`	weight applied to `p1`
`v1`	`Readonly`<`Vector3Like`>	the first point
`w2`	`number`	weight applied to `p2`
`v2`	`Readonly`<`Vector3Like`>	the second point

Returns

Vector3d

Example

let { Vector3d } = SketchUpApi;

// Midpoint between a and b
let mid = Vector3d.fromLinearCombination(
  0.5, [0, 0, 0], 0.5, [10, 20, 0]
);
console.log(mid.toArray());
// => [5, 10, 0]

NOTE this function will not create a unit vector, call Vector3d.normalize in order to achieve that.

Since

SDK 2.37.0

fromOrigin()

static fromOrigin(point): Vector3d

Creates a vector from the origin to a point — its components match the point’s coordinates. Useful when you have a position and need to treat it as a direction, like passing a point’s location into a method that expects a vector.

Parameters

Parameter	Type	Description
`point`	`Readonly`<`Point3Like`>	the point defining the vector’s components

Returns

Vector3d

Show Deprecated

Deprecated

to_a

Get Signature

get to_a(): [number, number, number]

Returns

[number, number, number]

angle_between()

angle_between(vector2): number

Parameters

Parameter	Type	Description
`vector2`	`Vector3d`	‐

Returns

number

parallel()

parallel(vector2): boolean

Parameters

Parameter	Type
`vector2`	`Readonly`<`Vector3Like`>

Returns

boolean