Three-viewport-gizmo NPM

Three Viewport Gizmo is a highly customizable standalone interactive version of the official three.js viewport helper, it can be used alone or in conjuncture with OrbitControls, TrackballControls or custom camera controllers like @yomotsu/camera-controls.

Examples

Installation

You can install Three Viewport Gizmo via npm:

npm install three-viewport-gizmo

Usage

Standalone

Use it with your camera and renderer instances, the container is the HTMLElement containing the canvas.

import { ViewportGizmo } from "three-viewport-gizmo";

const container = document.body;
const viewportGizmo = new ViewportGizmo(camera, renderer, options);

// Animation loop
function animate() {
  viewportGizmo.render();

  // ... Your animation logic
  renderer.render(scene, camera);
}

With OrbitControls or TrackBallControls

To properly work with OrbitControls or TrackballControls, you need to set the events listeners and animation loop as follow.

import { ViewportGizmo } from "three-viewport-gizmo";

const container = document.body;
const viewportGizmo = new ViewportGizmo(camera, renderer, options);
const controls = new OrbitControls(camera, container);

viewportGizmo.target = controls.target;

// listeners
viewportGizmo.addEventListener("start", () => (controls.enabled = false));
viewportGizmo.addEventListener("end", () => (controls.enabled = true));

controls.addEventListener("change", () => {
  viewportGizmo.update();
});

// Animation loop
function animate() {
  viewportGizmo.render();

  // ... Your animation logic
  renderer.render(scene, camera);

  // Update the OrbitControls
  if (controls.enabled) controls.update();
}

With @yomotsu/camera-controls

To set Three Viewport Gizmo with camera-controls, set the events listeners and the animation loop as the example below.

import * as THREE from "three";
import { ViewportGizmo } from "three-viewport-gizmo";
import CameraControls from "camera-controls";

CameraControls.install({ THREE });

// init
const container = document.body;
const viewportGizmo = new ViewportGizmo(camera, renderer, options);
const controls = new CameraControls(camera, container);

// listeners
viewportGizmo.addEventListener("start", () => {
  // Disable controls on change start
  controls.enabled = false;
});

viewportGizmo.addEventListener("end", () => {
  // Enable controls on change end
  controls.enabled = true;
});

viewportGizmo.addEventListener("change", () => {
  // Set the camera new position
  controls.setPosition(...camera.position.toArray());
});

controls.addEventListener("update", () => {
  // Update the the gizmo on controls update
  controls.getTarget(viewportGizmo.target);
  viewportGizmo.update();
});

// Animation loop
const clock = new THREE.Clock();
function animate() {
  viewportGizmo.render();

  // ... Your animation logic
  renderer.render(scene, camera);

  // Update the CameraControls
  if (controls.enabled && !viewportGizmo.animating)
    controls.update(clock.getDelta());
}

Configuration

You can customize the appearance and behavior of the gizmo by passing options during initialization:

const options = {
  container: HTMLElement;
  size: number;
  placement:
    | "top-left"
    | "top-right"
    | "top-center"
    | "center-right"
    | "center-left"
    | "center-center"
    | "bottom-left"
    | "bottom-right"
    | "bottom-center";
  lineWidth: number;
  offset: {
    left: number;
    top: number;
    right: number;
    bottom: number;
  };
  backgroundSphere: {
    enabled: boolean;
    color: ColorRepresentation;
    opacity: number;
  };
  font: {
    family?: string;
    weight?: string | number;
  };
  resolution: number;
  x: GizmoAxisOptions;
  y: GizmoAxisOptions;
  z: GizmoAxisOptions;
  nx: GizmoAxisOptions;
  ny: GizmoAxisOptions;
  nz: GizmoAxisOptions;
};

type GizmoAxisOptions = {
  text?: string;
  drawCircle?: boolean;
  drawLine?: boolean;
  border?: boolean;
  colors: Partial<{
    main: ColorRepresentation | [ColorRepresentation, ColorRepresentation];
    hover?: ColorRepresentation;
    text?: ColorRepresentation;
    hoverText?: ColorRepresentation;
  }>;
};

const viewportGizmo = new ViewportGizmo(camera, renderer, options);