DimensionLinear

A linear dimension that measures and displays the distance between two points in 3D space.

Linear dimensions are the annotation lines you see in architectural and engineering drawings — they show measurements between two endpoints, with arrows and text displaying the distance. In SketchUp, you create them with the Dimension tool or programmatically with createDimensionLinear().

Each dimension can attach to entities (edges, vertices, construction points) or free points in space. When attached to entities inside groups or components, the dimension follows those entities as they move.

Attachment behavior:

Attaching to an entity inside a group: the instance path contains the path to that group plus the entity.
Attaching to a point inside a group: the instance path contains the path to that group.
Attaching to an instance path inside a component definition with no instances: the attachment path is undefined until an instance is created, then refers to the first instance.

Example

let model = await SketchUpApi.getActiveModel();

// Draw two edges to create reference points.
await model.performOperation(op => {
  op.createEdge(model, [[0, 0, 0], [100, 0, 0]]);
  op.createEdge(model, [[0, 50, 0], [100, 50, 0]]);
}, 'Draw edges');

// Add a dimension between the edge endpoints.
await model.performOperation(op => {
  const start = [0, 0, 0];
  const end = [100, 0, 0];
  const offset = [0, 0, 20]; // Text above line
  op.createDimensionLinear(
    model, start, end, offset
  );
}, 'Add dimension');

// Query back and inspect.
let dims = await model.entities.get({
  filterBy: { types: ['DimensionLinear'] }
});
console.log(dims[0].text);
// => '100.0"' (or metric equivalent)
console.log(
  dims[0].startPoint, dims[0].endPoint
);
// => [0, 0, 0] [100, 0, 0]

See

Since

SDK 2.23.0 Protocol 1.20.0

Extends

BaseDrawingElement

Properties

alignedTextPosition

readonly alignedTextPosition: DimensionAlignedTextPosition

Where the text is positioned along the dimension line when hasAlignedText is true. Can be centered on the line, at either end, or outside the measured region.

arrowType

readonly arrowType: DimensionArrowType

The arrow style used at both ends of the dimension line. Controls the appearance of endpoint markers — arrows, slashes, dots, or none.

attributes

readonly attributes: Attributes

The attribute dictionaries attached to this element. Attributes store custom key-value metadata that extensions can read and write.

Inherited from

BaseDrawingElement.attributes

castsShadows

readonly castsShadows: boolean

Whether this element casts shadows onto other geometry.

Inherited from

BaseDrawingElement.castsShadows

endAttachedTo

readonly endAttachedTo: InstancePath | undefined

The instance path to the end attachment when the dimension is attached to geometry inside a group or component. undefined if attached to top-level geometry or a free point.

endEntity

readonly endEntity: EntityRef | undefined

A reference to the entity the end is attached to, if any. When the dimension snaps to a vertex, edge, or construction point, this ref points to that entity. undefined if the end is a free point in space.

endPoint

readonly endPoint: Point3d

The 3D coordinate where the dimension measurement ends. This is the final endpoint shown by the dimension, regardless of attachment.

hasAlignedText

readonly hasAlignedText: boolean

Whether the dimension text is aligned parallel to the measurement line (true) or kept horizontal/vertical regardless of line angle (false).

hidden

readonly hidden: boolean

Whether this element is hidden. Hidden elements don’t appear in the viewport unless the user enables “View > Hidden Geometry.”

Inherited from

BaseDrawingElement.hidden

id

readonly id: number

The persistent ID that uniquely identifies this dimension.

materialRef

readonly materialRef: MaterialRef | undefined

A reference to the material applied to this element, if any. Call getMaterial() to fetch the full Material object with color and texture data.

Inherited from

BaseDrawingElement.materialRef

offsetVector

readonly offsetVector: Vector3d

The 3D vector from the line connecting the start and end points to the actual dimension line position. Determines how far the dimension is offset from the measured geometry.

plane

readonly plane: Plane

The plane on which the dimension is drawn. The dimension line, arrows, and text all lie within this plane.

receivesShadows

readonly receivesShadows: boolean

Whether this element receives shadows cast by other geometry.

Inherited from

BaseDrawingElement.receivesShadows

startAttachedTo

readonly startAttachedTo: InstancePath | undefined

The instance path to the start attachment when the dimension is attached to geometry inside a group or component. undefined if attached to top-level geometry or a free point.

startEntity

readonly startEntity: EntityRef | undefined

A reference to the entity the start is attached to, if any. When the dimension snaps to a vertex, edge, or construction point, this ref points to that entity. undefined if the start is a free point in space.

startPoint

readonly startPoint: Point3d

The 3D coordinate where the dimension measurement starts. This is the starting endpoint shown by the dimension, regardless of attachment.

tagRef

readonly tagRef: TagRef | undefined

A reference to the tag (formerly “layer”) assigned to this element. Call getTag() to fetch the full Tag object.

Inherited from

BaseDrawingElement.tagRef

text

readonly text: string

The formatted text displayed by the dimension, like "100.0"" or "2.54 m". Reflects the model’s current unit settings and any custom text overrides applied to the dimension.

textPosition

readonly textPosition: DimensionTextPosition

Where the text is positioned relative to the dimension line — above, centered, or below.

type

readonly type: DimensionLinear = EntityType.DimensionLinear

Accessors

sketchupId

Get Signature

get sketchupId(): SketchupId

JS API identifier for this dimension. Pass it to API methods that accept a sketchupId.

Returns

SketchupId

Overrides

BaseDrawingElement.sketchupId

typeName

Get Signature

get typeName(): string

Returns a named variant of the type field.

Since

SDK 2.35.0

Returns

string

Methods

getBounds()

getBounds(): Promise<BoundingBox>

Fetches the axis-aligned bounding box for this element from SketchUp.

Returns

Promise<BoundingBox>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let box = await element.getBounds();
console.log(box.min.x, box.min.y, box.min.z);
console.log(box.max.x, box.max.y, box.max.z);

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getBounds

getMaterial()

getMaterial(): Promise<Material | undefined>

Fetches the material applied to this element. Returns undefined if the element uses the default material.

Returns

Promise<Material | undefined>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let mat = await element.getMaterial();
if (mat) {
  console.log(mat.name, mat.color.toHex());
}

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getMaterial

getTag()

getTag(): Promise<Tag | undefined>

Fetches the tag assigned to this element. Most elements have a tag — even those on the default “Untagged” tag. Returns undefined only if the tag reference is missing.

Returns

Promise<Tag | undefined>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let tag = await element.getTag();
if (tag) {
  console.log(tag.name);
}

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getTag

refresh()

refresh(): Promise<DimensionLinear>

Re-fetches this dimension from SketchUp to get its current state. Because DimensionLinear is a snapshot, it can become stale if the model changes. Call refresh() to get an up-to-date copy.

Returns

Promise<DimensionLinear>

A new DimensionLinear reflecting the current model state. Throws if the dimension has been deleted.

Example

let model = await SketchUpApi.getActiveModel();
let dims = await model.entities.get({
  filterBy: { types: ['DimensionLinear'] },
});
// Later, after the user makes changes...
let fresh = await dims[0].refresh();
console.log(fresh.text, fresh.offsetVector);

toString()

toString(): string

Returns a string representation of an object.

Returns

string

Show Deprecated

Deprecated

materialId

readonly materialId: number | undefined

Inherited from

BaseDrawingElement.materialId

tagId

readonly tagId: number | undefined

Inherited from

BaseDrawingElement.tagId

bounds

Get Signature

get bounds(): Promise<BoundingBox>

Returns

Promise<BoundingBox>

Inherited from

BaseDrawingElement.bounds