CanvasExportPlugin

Exports the viewer canvas as a PNG, JPEG, or WebP image. Optionally composites the label overlay and includes or excludes measurement geometry.

Usage

Register the plugin, then call exportImage for a data URL or downloadImage to trigger a browser download.

import { ViewerCore, CanvasExportPlugin } from "@optellix/xviewr-sdk";

const viewer = new ViewerCore(container, config);
await viewer.ready();
await viewer.loadPlugin(new CanvasExportPlugin());

const exporter = viewer.pluginManager.getPlugin("canvas-export") as CanvasExportPlugin;
const dataUrl = await exporter.exportImage({ width: 1920, height: 1080, format: "png" });

No service dependencies. The plugin reads from the active renderer, scene, and camera directly.

Public API

Method	Description
exportImage(options?)	Render the scene at the requested size and return a data URL.
downloadImage(options?)	Same as exportImage, then trigger a download via a temporary <a> element.

Both methods are async. The renderer is temporarily resized for the capture and restored before returning.

Options

CanvasExportOptions:

Field	Type	Default	Notes
width	number	renderer canvas width	Output width in pixels.
height	number	renderer canvas height	Output height in pixels.
format	"png" | "jpeg" | "webp"	"png"	Output image format.
quality	number	0.92	0..1, applies to lossy formats.
includeMeasurements	boolean	true	When false, hides objects with userData.isMeasurement === true for the capture.
includeLabels	boolean	true	When true, rasterises .xv-label-overlay DOM via snapdom and draws it on top.
background	"viewer" | "transparent"	"viewer"	"viewer" fills with the renderer clear color first.
filename	string	xviewr-canvas.<format>	Used by downloadImage.

Events

Event	Payload
canvas-export:started	{ options }
canvas-export:completed	{ options, dataUrl, width, height, format }
canvas-export:error	{ options, error }

Example

const exporter = viewer.pluginManager.getPlugin("canvas-export") as CanvasExportPlugin;

await exporter.downloadImage({
  width: 3840,
  height: 2160,
  format: "jpeg",
  quality: 0.95,
  includeMeasurements: false,
  background: "transparent",
  filename: "scene-4k.jpg",
});