ImageEntityRef

A lightweight placeholder for an Image that hasn’t been fully loaded yet.

When you create an image inside a SketchupOperation, the API returns an ImageEntityRef immediately, before SketchUp has finished processing it. You can pass these refs to other operation methods (like positioning or transforming the image), but if you need the full ImageEntity instance — with properties like width, height, and transformation — you can request it with entityForRef().

Think of a ref as a “claim ticket” — it guarantees an image will exist after the operation commits, but it doesn’t carry the image’s properties yet. A ref is only valid inside the performOperation callback that created it — do not return it or use it after the operation commits.

Example

let model = await SketchUpApi.getActiveModel();

await model.performOperation(async op => {
  // 1x1 yellow pixel PNG (use any data URL)
  const px = 'data:image/png;base64,iVBORw0KGg'
    + 'oAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ'
    + 'AAAADUlEQVR42mP8/5+hHgAHggJ/PchI7'
    + 'wAAAABJRU5ErkJggg==';
  const imageRef = op.createImage(model, {
    resource: { dataUrl: px },
    origin: [0, 0, 0],
    width: 100,
    height: 100,
  });
  // Resolve to get full ImageEntity
  const image = await op.entityForRef(imageRef);
  console.log(image.width, image.height);
  // => 100 100 (display size in inches)
  console.log(image.imageWidth, image.imageHeight);
  // => 1 1 (pixel resolution)
}, 'Place a reference image');

See

Properties

sketchupId

readonly sketchupId: SketchupId

type

readonly type: Image = EntityType.Image

Accessors

typeName

Get Signature

get typeName(): string

Returns a named variant of the type field.

Since

SDK 2.35.0

Returns

string

Methods

toString()

toString(): string

Returns

string