ImageViewerPlugin

2D image viewer with zoom-to-cursor and pan. Renders into a <canvas> inside a provided container. Independent of the 3D pipeline; useful for reference images and as a backdrop for MarkupPlugin.

Usage

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

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

const imageViewer = new ImageViewerPlugin({
  container: document.getElementById("image-panel")!,
  src: "/drawings/part-001.png",
  maxZoom: 12,
});
await viewer.loadPlugin(imageViewer);

No service dependencies. The plugin owns its own canvas, pointer events, and resize observer.

Constructor

new ImageViewerPlugin(config: ImageViewerConfig)

ImageViewerConfig

Field	Type	Default	Description
container	HTMLElement	required	Host element. Will be set to position: relative; overflow: hidden.
src	string	undefined	Initial image URL. Loaded on activate.
zoomSensitivity	number	0.001	Wheel multiplier per delta unit.
maxZoom	number	10	Upper zoom limit. The minimum is computed to fit the image.
onTransformChange	(transform) => void	undefined	Fires on every pan, zoom, or resize.

ImageTransform

interface ImageTransform {
  scale: number;
  offsetX: number;
  offsetY: number;
  minZoom: number;
  maxZoom: number;
}

Public API

Method	Description
loadImage(src)	Load a new image. Resets pan and zoom to fit.
getTransform()	Returns the current ImageTransform.
getCanvas()	Returns the underlying <canvas> (or null when inactive).
resetView()	Reset to fit-the-container scale and center.

Events

The plugin does not use the event bus. Use onTransformChange for transform updates.

Example

const imageViewer = new ImageViewerPlugin({
  container: document.getElementById("image-panel")!,
  onTransformChange: (t) => markup.syncTransform(t),
});
await viewer.loadPlugin(imageViewer);

await imageViewer.loadImage("/drawings/part-001.png");
imageViewer.resetView();