Photo Capture and Preview

Related reference: Scene API / Camera and Photo Capture

The current Web plugin provides photo capture capabilities. You can use the default photo button or fully customize the experience from the host page.

Default Photo Button

By default, Kivicube shows a photo button at the appropriate time:

• in web3d scenes it is usually visible relatively early
• in image-tracking scenes it usually appears only after tracked

To hide the default button:

await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId,
  hideTakePhoto: true,
});

Trigger Photo Capture with the Advanced API

iframe.addEventListener('ready', async (event) => {
  const { api } = event.detail;

  const imageUrl = await api.takePhoto();
  console.log(imageUrl);
});

takePhoto() returns an image URL in the form data:image/png;base64,....

What the Captured Photo Contains

The current implementation:

1. captures the 3D scene first
2. if the scene is AR, captures one frame of camera imagery
3. composites them into a final image

So the result is usually a composite of "camera view + 3D content".

In some cases, the photo may also contain a watermark.

The photo content matches whatever the iframe currently contains.

The output resolution depends on the device resolution and DPR, so it is not fixed.

Custom Preview

The simplest host-layer approach is to assign the returned value directly to an <img>:

const photo = await api.takePhoto();
previewImg.src = photo;
previewDialog.open = true;

Download the Image

const photo = await api.takePhoto();
const link = document.createElement('a');
link.href = photo;
link.download = 'kivicube-photo.png';
link.click();

Recommended UX

A common flow is:

1. hide the default photo button
2. place a branded button on the host layer
3. call api.takePhoto() when the user clicks
4. open a custom preview layer
5. provide three actions: save, retake, and share

Notes

• Photo capture is asynchronous, so show a loading state to avoid repeated taps.
• If the page shows a standard watermark, the captured result should also contain it.
• Always validate the final image resolution and crop behavior on real phones.