Images / Panoramas

Related reference: Scene API / Dynamic Content Creation

The Web plugin currently provides two common static image capabilities:

• standard image objects
• panorama objects

Standard Images

Create an Image

const image = await api.createImage('https://your.domain.com/banner.png');
await api.add(image);

You can also pass an ArrayBuffer:

const response = await fetch('/assets/banner.png');
const buffer = await response.arrayBuffer();

const image = await api.createImage(buffer);
await api.add(image);

Set Position and Scale

await api.setPosition(image, 0, 0.5, 0);
await api.setScale(image, 1.2, 1.2, 1.2);

Basic Events

Image objects are clickable, so you can listen for:

await api.on('click', (event) => {
  console.log(event);
}, image);

Panoramas

Create a Panorama

const panorama = await api.createPanorama(
  'https://your.domain.com/panorama.jpg',
  64,
);

await api.add(panorama);

The second parameter, segments, controls the geometry subdivision. In most cases it does not need to be very high. The default is 64.

Panoramas do not support click events.

They do support position, scale, and rotation.

Difference Between Images and Panoramas

Type	Typical use
Image	Posters, flat decals, UI-like elements, 2D content
Panorama	Web3D backgrounds, immersive scene wrapping

Supported Image Formats

Only common image formats are supported: jpeg / jpg / png / gif.

Note: only images in the sRGB color space are supported. In most cases, exports from Photoshop already use that setup.

Extra Notes for Web3D Backgrounds

If the scene editor does not explicitly configure a panorama background, the runtime inserts a default background container. So:

• you can use a panorama in the scene editor as the main background
• or create and replace the panorama object at runtime

Recommended Practices

1. Treat UI-like images as separate objects whenever possible, so the host layer can control visibility and click handling.
2. Put large images on a CDN first and make sure CORS is configured correctly.