ImageEntity

A flat image placed in 3D space, used for reference photos, decals, or texture previews.

Images in SketchUp are rectangular planes that display bitmap data (PNG, JPG, etc.) at a specific position and orientation. They’re not geometry — they don’t create faces — but they can be queried, transformed, and exported. Images are often used as modeling references (like blueprints) or for visual context (like site photos).

Each image has both a pixel resolution (imageWidth × imageHeight) and a physical size (width × height in inches). The physical size determines how large it appears in the model, while the pixel dimensions control the visual fidelity.

Example

let model = await SketchUpApi.getActiveModel();

// Create a small 2x2 canvas with a gradient.
let canvas = document.createElement('canvas');
canvas.width = 2;
canvas.height = 2;
let ctx = canvas.getContext('2d');
let grad = ctx.createLinearGradient(0, 0, 2, 2);
grad.addColorStop(0, '#ff0000');
grad.addColorStop(1, '#0000ff');
ctx.fillStyle = grad;
ctx.fillRect(0, 0, 2, 2);

// Place it in the model as a 50" wide image.
let dataUrl = canvas.toDataURL();
await model.performOperation(op => {
  op.createImage(model, {
    resource: { dataUrl },
    origin: [0, 0, 0],
    width: 50,
  });
}, 'Place gradient image');

// Query the image back and read its properties.
let images = await model.entities.get({
  filterBy: { types: ['Image'] }
});
let img = images[0];
console.log(img.width, img.height);
// => 50 50 (physical size in inches)
console.log(img.imageWidth, img.imageHeight);
// => 2 2 (pixel resolution)
console.log(img.origin.toArray());
// => [0, 0, 0]
console.log(img.normal.toArray());
// => [0, 0, 1]

See

Since

SDK 2.21.0 Protocol 1.19.0

Extends

BaseDrawingElement

Properties

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

fileName

readonly fileName: string

The original filename of the image when it was imported, like “blueprint.png”. This may be a generated name if the image was created from raw data.

gluedToId

readonly gluedToId: SketchupId | undefined

The ID of the face this image is glued to, if any. Glued images move with the face and inherit its orientation. Returns undefined if the image is free-standing.

height

readonly height: number

The physical height of the image as it appears in the model, measured in inches. This is independent of the pixel resolution — a 10-pixel-tall image can be displayed at 100 inches tall.

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 image.

imageHeight

readonly imageHeight: number

The height of the underlying bitmap in pixels.

imageWidth

readonly imageWidth: number

The width of the underlying bitmap in pixels.

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

receivesShadows

readonly receivesShadows: boolean

Whether this element receives shadows cast by other geometry.

Inherited from

BaseDrawingElement.receivesShadows

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

transform

readonly transform: Transformation

The transformation matrix that positions and orients this image in 3D space. The origin is the image’s lower-left corner, and the Z-axis points out from the image plane.

type

readonly type: Image = EntityType.Image

width

readonly width: number

The physical width of the image as it appears in the model, measured in inches. This is independent of the pixel resolution — a 10-pixel-wide image can be displayed at 100 inches wide.

Accessors

normal

Get Signature

get normal(): Vector3d

The direction the image faces — a unit vector perpendicular to the image plane. This is a convenience accessor for transform.zaxis. If the image is glued to a face, the normal will match the face’s orientation.

Example

let model = await SketchUpApi.getActiveModel();
let images = await model.entities.get({
  filterBy: { types: ['Image'] }
});
console.log(images[0].normal.toArray());
// => [0, 0, 1] (facing up along the Z-axis)

Returns

Vector3d

origin

Get Signature

get origin(): Point3d

The position of the image’s lower-left corner in 3D space. This is a convenience accessor for transform.origin.

Example

let model = await SketchUpApi.getActiveModel();
let images = await model.entities.get({
  filterBy: { types: ['Image'] }
});
console.log(images[0].origin.toArray());
// => [120, 0, 0]

Returns

Point3d

sketchupId

Get Signature

get sketchupId(): SketchupId

JS API identifier for this image. 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

zrotation

Get Signature

get zrotation(): number

The rotation angle of the image around its normal vector, measured in radians. Zero means the image’s X-axis aligns with the world X-axis (assuming the normal is [0, 0, 1]). This is a convenience accessor for transform.zrotation.

Example

let model = await SketchUpApi.getActiveModel();
let images = await model.entities.get({
  filterBy: { types: ['Image'] }
});
let degrees = images[0].zrotation * (180 / Math.PI);
console.log(degrees);
// => 45.0 (rotated 45 degrees)

Returns

number

Methods

export()

export(fileType): Promise<string>

Exports the image’s bitmap data as a base64-encoded string in the specified format. Use this to extract the underlying texture for saving to disk or displaying in a web page. The returned string is raw base64 — prepend a data URL prefix like data:image/png;base64, if needed for HTML.

Note that GIF export is not supported in the web version of SketchUp due to browser limitations.

Parameters

Parameter	Type	Description
`fileType`	`ImageFileType`	The file type that the data should be encoded as (e.g., “png”, “jpg”, “bmp”). Pass an `ImageFileType` constant.

Returns

Promise<string>

A promise containing the base64-encoded image data.

Example

let model = await SketchUpApi.getActiveModel();
let images = await model.entities.get({
  filterBy: { types: ['Image'] }
});
let base64 = await images[0].export('png');
console.log(base64.substring(0, 20));
// => iVBORw0KGgoAAAANSUhE...

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

Re-fetches this image from SketchUp to get its current state. Because ImageEntity is a snapshot, it can become stale if the model changes (e.g., if the user moves or resizes the image). Call refresh() to get an up-to-date copy.

Returns

Promise<ImageEntity>

A new ImageEntity reflecting the current model state. Throws if the image has been deleted.

Example

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

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