🔄 Live Angle Thumbnails

A shopper picks a fabric, then a leg finish, then a different fabric again. Your product gallery is still showing the photography from the original catalogue shot - the thumbnails no longer match what's on screen.

Live angle thumbnails fix that. Tell the configurator which angles you want and it sends your page a set of small renders of exactly what's on screen, from those angles - first as soon as the product has loaded, then again every time the shopper's configuration settles. Drop them into your gallery strip, and clicking one can turn the live 3D viewer round to match.

They're rendered in the shopper's browser from the live scene, so they always match - same materials, same lighting, same tone mapping and shadows as the big viewer. Backgrounds are transparent, so they sit on whatever your page uses.

Quick start

Ask for some angles on the configurator URL:

https://configurator.orbital.vision/{apiKey}/{productId}?cutoutAngles=0,-45,-135

Then listen for them on your page:

window.addEventListener('message', (event) => {
  if (event.data?.type !== 'CUTOUT_THUMBNAILS') return;
 
  const { bitmaps, yaws } = event.data;
  // bitmaps[i] is the render for angle yaws[i]
});

That's the whole feature. Nothing happens unless you pass cutoutAngles - no extra rendering, no messages.

Using the ov25-ui package? productLink accepts a query string and merges it into the iframe URL, and the message still arrives on your page's window:

injectConfigurator({
  apiKey: () => 'your-api-key',
  productLink: () => '92?cutoutAngles=0,-45,-135',
  // ...the rest of your config
});

Choosing angles

cutoutAngles is a comma-separated list of absolute yaw angles in degrees:

• 0 faces the front of the product.
• Negative walks left around it, positive walks right.
• 180 (or -180) is the back.

So 0,-45,-135 gives you a front shot, a left three-quarter, and a left-back three-quarter.

They're absolute, so you don't need to know anything about how a particular product's camera was set up - 0 is the front of a footstool and the front of a corner sofa alike. Everything else about the shot (height, lens, and how tightly the product is framed) comes from the product's own default camera, so the thumbnails look like the main viewer rather than a generic render.

Each angle is one extra render, repeated every time the configuration changes, so keep the list short - three or four is a comfortable number. Ask for the smallest cutoutSize that still looks sharp at the size you display it; the default 200 is deliberately tiny because the tiles are usually 100px or so on screen.

Receiving the thumbnails

The first set arrives on its own once the 3D scene has loaded - the shopper doesn't have to touch anything. After that, every time the configuration settles, the configurator sends the complete current set - not just what changed. Replace whatever you were holding and you're always in sync; there's no patching or bookkeeping to do.

The message is deliberately not JSON - the images come across as ImageBitmap objects, which transfer without being copied or base64-encoded:

ImageBitmap can be drawn straight to a <canvas>. If you'd rather have something you can put in an <img> tag, convert them as they arrive:

window.addEventListener('message', (event) => {
  if (event.data?.type !== 'CUTOUT_THUMBNAILS') return;
 
  const { bitmaps, yaws } = event.data;
 
  const tiles = bitmaps.map((bitmap, i) => {
    const canvas = document.createElement('canvas');
    canvas.width = bitmap.width;
    canvas.height = bitmap.height;
    canvas.getContext('2d').drawImage(bitmap, 0, 0);
    bitmap.close(); // release it once you've copied the pixels out
 
    return { url: canvas.toDataURL('image/png'), angle: yaws[i] };
  });
 
  renderMyThumbnailStrip(tiles); // your code
});

Clicking a thumbnail to turn the viewer

Send SELECT_CUTOUT_ANGLE back to the iframe to turn the live 3D viewer to one of the angles you were sent:

iframe.contentWindow.postMessage({
  type: 'SELECT_CUTOUT_ANGLE',
  payload: JSON.stringify({ yawDeg: -45 }),
}, '*');

The camera swings round to that angle at the product's opening framing, undoing any zoom the shopper applied. It's a shortcut rather than a lock: the shopper can carry on dragging from there, and grabbing the viewer mid-move stops it.

When the camera has arrived and that frame is on screen, the configurator replies with CUTOUT_CAMERA_PRESENTED. Its payload is a JSON string of { yawDeg, requestId }. Wait for it before taking down anything you were showing over the viewer:

window.addEventListener('message', (event) => {
  if (event.data?.type !== 'CUTOUT_CAMERA_PRESENTED') return;
 
  const { yawDeg, requestId } = JSON.parse(event.data.payload);
  // The live viewer is now showing yawDeg - safe to reveal it.
});

A "360°" tile alongside your thumbnails doesn't need to move the camera: send yawDeg: null so any move still in progress stops, and show the live viewer.

MOVE_CAMERA_TO_CUTOUT_ANGLE is accepted as another name for the same message.

Recipes

Behaviour notes

• Off by default. With no cutoutAngles parameter the configurator behaves exactly as it always has - nothing is rendered and no messages are sent. An empty or invalid value is treated the same way.
• The first set arrives without any interaction, a moment after the 3D scene finishes loading. Keep your existing imagery in place until it turns up, so the gallery isn't empty while the product loads.
• Renders are captured off-screen and never disturb the shopper's view - the live viewer doesn't flicker or move while a set is being produced.
• Rapid changes are coalesced: click through five fabrics quickly and you'll get one set for the configuration you land on, not five.
• Backgrounds are fully transparent, and the product is framed the same way in every angle.
• Available on the standard product configurator. The bed, dining, and Snap2 modular configurators have their own embeds and don't support this yet.