ViewCubePlugin

Interactive navigation cube rendered as an overlay in a corner of the main viewport. Click faces, edges, or corners to snap the camera. Drag the cube to free-rotate.

Usage

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

const viewer = new ViewerCore(container, config);
await viewer.ready();
await viewer.loadPlugin(new ViewCubePlugin({ anchor: "top-right", size: 140 }));

Service dependencies: camera, animation. The cube draws into the main viewport via a post-render callback (no separate canvas).

Constructor

new ViewCubePlugin(options?: ViewCubePluginOptions)

ViewCubePluginOptions

Field	Type	Default	Description
anchor	ViewCubeAnchor	"top-right"	Corner anchor.
size	number	136	Cube viewport size in pixels. Capped by available canvas size. Minimum 48.
offset	number	20	Pixel offset from the anchored corner.
animationDuration	number	650	Snap animation duration in ms.

type ViewCubeAnchor = "top-left" | "top-right" | "bottom-left" | "bottom-right";

Public API

Method	Description
focusPreset(preset, duration?)	Animate to a named view: "front" | "back" | "left" | "right" | "top" | "bottom".
focusDirection(direction, duration?)	Animate to face the scene from an arbitrary THREE.Vector3 direction.
show()	Show the cube.
hide()	Hide the cube and clear hover state.
isVisible()	Boolean.

Events

Event	Payload
viewcube:navigate	{ hotspot, kind, direction } emitted on click snap. kind is "face" | "edge" | "corner".
camera:changed	{ position, target } emitted on every applied pose during snap and drag.

Example

import * as THREE from "three";

await viewer.loadPlugin(new ViewCubePlugin({
  anchor: "bottom-right",
  size: 160,
  offset: 24,
  animationDuration: 500,
}));

const cube = viewer.pluginManager.getPlugin("viewcube") as ViewCubePlugin;
await cube.focusPreset("top");
await cube.focusDirection(new THREE.Vector3(1, 1, 1));

viewer.eventBus.on("viewcube:navigate", ({ hotspot, kind }) => {
  console.log(`navigated to ${kind} ${hotspot}`);
});