Point3d

A position in 3D space, measured in inches.

Point3d is the fundamental coordinate type in the SketchUp API. Every vertex, construction point, and camera position is ultimately a Point3d. Coordinates are always in inches — SketchUp’s internal unit — regardless of what display units the model is configured to show.

Points are immutable: methods like add() and subtract() return new instances rather than modifying the original.

Example

let { Point3d } = SketchUpApi;

let a = new Point3d(10, 20, 0);
let b = new Point3d(40, 60, 0);

console.log(a.distance(b));
// => 50 (inches)

// Offset a point by a vector
let moved = a.add([5, 5, 10]);
console.log(moved.toArray());
// => [15, 25, 10]

// Compare with tolerance
let c = new Point3d(10.0005, 20, 0);
console.log(a.equalTo(c));
// => true (within default 0.001" tolerance)

See

Constructor

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

Parameters

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

Returns

Point3d

Properties

x

readonly x: number = 0

y

readonly y: number = 0

z

readonly z: number = 0

Methods

add()

add(input): Point3d

Returns a new point offset by the given vector or array. Does not modify this point.

Parameters

Parameter	Type	Description
`input`	`Readonly`<`Point3Like`>	‐

Returns

Point3d

Example

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

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

distance()

distance(point): number

The straight-line distance to another point, in inches.

Parameters

Parameter	Type	Description
`point`	`Readonly`<`Point3Like`>	‐

Returns

number

Example

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

// ~33.67
console.log(a.distance(b));

distanceToLine()

distanceToLine(ray): number

Calculates the closest distance between this point and the given line (ray)

Parameters

Parameter	Type	Description
`ray`	`Readonly`<`Ray3dLike`>	‐

Returns

number

Example

let { Point3d } = SketchUpApi;
let a = new Point3d(1,2,3);
let b = new Point3d(4,5,6);
let c = new Point3d(7,8,9);

// 0
console.log(c.distanceToLine([a, b]));

Since

SDK 2.37.0

distanceToPlane()

distanceToPlane(plane): number

Calculates the closest distance between this point and the given plane.

NOTE The distance is unsigned, it cannot tell you if the value is above or below the plane

Parameters

Parameter	Type	Description
`plane`	`Readonly`<`PlaneLike`>	‐

Returns

number

Example

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

// 2
console.log(a.distanceToPlane([0, 0, 1, -5]));

Since

SDK 2.37.0

equalTo()

equalTo(point, tol?): boolean

Compares two points component-wise within a tolerance. The default tolerance is 0.001” — close enough for SketchUp’s internal precision.

Parameters

Parameter	Type	Default value	Description
`point`	`Readonly`<`Point3Like`>	`undefined`	‐
`tol`	`number`	`Point3d.EqualTol`	per-axis tolerance in inches, defaults to 0.001

Returns

boolean

Example

let { Point3d } = SketchUpApi;
let a = new Point3d(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])));

isOnLine()

isOnLine(ray, tolerance?): boolean

Returns true if point is on the given line (ray) within a supplied tolerance.

Parameters

Parameter	Type	Default value	Description
`ray`	`Readonly`<`Ray3dLike`>	`undefined`	the ray
`tolerance`	`number`	`Point3d.EqualTol`	defaults to 0.001

Returns

boolean

Example

let { Point3d } = SketchUpApi;
let a = new Point3d(1,2,3);
let b = new Point3d(4,5,6);
let c = new Point3d(7,8,9);

// true
console.log(c.isOnLine([a, b]));

Since

SDK 2.37.0

isOnPlane()

isOnPlane(plane, tolerance?): boolean

Returns true if this point sits on the given plane within the tolerance in inches.

Parameters

Parameter	Type	Default value	Description
`plane`	`Readonly`<`PlaneLike`>	`undefined`	‐
`tolerance`	`number`	`Point3d.EqualTol`	defaults to 0.001

Returns

boolean

Example

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

// false
console.log(a.isOnPlane([0, 0, 1, -5]));
// true
console.log(a.isOnPlane([0, 0, 1, -3]));

Since

SDK 2.37.0

offset()

offset(input, distance?): Point3d

Creates a new point using the given offset and distance

Parameters

Parameter	Type	Description
`input`	`Readonly`<`Vector3Like`>	‐
`distance?`	`number`	the distance along the vector to move the new point. When not supplied, the length of the vector is assumed to be the distance.

Returns

Point3d

Point3d

Example

let { Point3d } = SketchUpApi;
let a = new Point3d(1,2,3);
// Vector3d(101,2,3)
console.log(a.offset([100,0,0]).toString());
// Vector3d(-9,2,3)
console.log(a.offset([100,0,0],-10).toString());

Since

SDK 2.37.0

projectToLine()

projectToLine(ray): Point3d

Returns the point along the line (ray) that is closest to this point.

Parameters

Parameter	Type	Description
`ray`	`Readonly`<`Ray3dLike`>	‐

Returns

Point3d

Example

let { Point3d } = SketchUpApi;
let a = new Point3d(1,2,3);
let b = new Point3d(4,5,6);
let c = new Point3d(100,101,0);

// ~ Point3d(100,101,102)
console.log(c.projectToLine([a, b]));

Since

SDK 2.37.0

projectToPlane()

projectToPlane(plane): Point3d

Returns the closest point to this point on the given plane.

Parameters

Parameter	Type	Description
`plane`	`Readonly`<`PlaneLike`>	‐

Returns

Point3d

Example

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

// Point3d(1,2,5)
console.log(a.projectToPlane([0, 0, 1, -5]));

Since

SDK 2.37.0

signedDistanceToPlane()

signedDistanceToPlane(plane): number

Calculates the closest distance between this point and the given plane.

Returns a positive value if the point is “above” the plane, negative otherwise.

Parameters

Parameter	Type	Description
`plane`	`Readonly`<`PlaneLike`>	‐

Returns

number

Example

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

// 2
console.log(a.distanceToPlane([0, 0, 1, -5]));

Since

SDK 2.37.0

subtract()

subtract(input): Point3d

Returns a new point shifted in the opposite direction of the given vector or array. Does not modify this point.

Parameters

Parameter	Type	Description
`input`	`Readonly`<`Point3Like`>	‐

Returns

Point3d

Example

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

// Point3d(-9,-18,-27);
console.log(a.subtract(b).toString());

toArray()

toArray(): [number, number, number]

Returns this point as an [x, y, z] tuple — handy for logging or passing to methods that accept arrays.

Returns

[number, number, number]

Since

SDK 2.35.0

toString()

toString(): string

Returns

string

toVector()

toVector(): Vector3d

Converts this point to a vector from the origin — same x, y, z values but interpreted as a direction/displacement.

Returns

Vector3d

with()

with(partialPoint): Point3d

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

Null and undefined values are ignored.

Parameters

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

Returns

Point3d

Example

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

Since

SDK 2.37.0

create()

static create(input): Point3d

Converts a Point3Like into a Point3d instance. If you already have a Point3d, it’s returned as-is. Useful when writing your own functions that accept a Point3Like and need a concrete Point3d to call methods on.

Parameters

Parameter	Type	Description
`input`	`Readonly`<`Point3Like`>	anything shaped like a Point3d

Returns

Point3d

Example

let { Point3d } = SketchUpApi;

let fromArray = Point3d.fromPoint3Like([10, 20, 0]);
console.log(fromArray.toArray());
// => [10, 20, 0]

let p = new Point3d(5, 5, 5);
console.log(Point3d.fromPoint3Like(p) === p);
// => true (already a Point3d, returned as-is)

Since

SDK 2.37.0

fromLinearCombination()

static fromLinearCombination(w1, p1, w2, p2): Point3d

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`
`p1`	`Readonly`<`Point3Like`>	the first point
`w2`	`number`	weight applied to `p2`
`p2`	`Readonly`<`Point3Like`>	the second point

Returns

Point3d

Example

let { Point3d } = SketchUpApi;

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

Show Deprecated

Deprecated

to_a

Get Signature

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

Returns

[number, number, number]

fromPoint2Like()

static fromPoint2Like(input): Point3d

Creates a Point3d from an [x, y] tuple, with z set to 0. Useful for 2D contexts — like screen coordinates or a flat sketch — where a Z coordinate doesn’t apply.

Parameters

Parameter	Type	Description
`input`	[`number`, `number`]	an `[x, y]` tuple

Returns

Point3d

Example

let { Point3d } = SketchUpApi;

let p = Point3d.fromPoint2Like([10, 20]);
console.log(p.toArray());
// => [10, 20, 0]

fromPoint3Like()

static fromPoint3Like(input): Point3d

Converts a Point3Like into a Point3d instance. If you already have a Point3d, it’s returned as-is. Useful when writing your own functions that accept a Point3Like and need a concrete Point3d to call methods on.

Parameters

Parameter	Type	Description
`input`	`Readonly`<`Point3Like`>	anything shaped like a Point3d

Returns

Point3d

Example

let { Point3d } = SketchUpApi;

let fromArray = Point3d.fromPoint3Like([10, 20, 0]);
console.log(fromArray.toArray());
// => [10, 20, 0]

let p = new Point3d(5, 5, 5);
console.log(Point3d.fromPoint3Like(p) === p);
// => true (already a Point3d, returned as-is)