Three Viewport Gizmo

https://fennec-hub.github.io/three-viewport-gizmo/
Admin
Three Viewport Gizmo is a lightweight, customizable 3D viewport orientation controller for Three.js...
Tokens:5,278
Snippets:47
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Three Viewport Gizmo via npm

Source: https://fennec-hub.github.io/three-viewport-gizmo/quickstart.html

Installs the ViewportGizmo library using npm. This is the recommended method for project integration.

```bash
npm install three-viewport-gizmo
```

--------------------------------

### Initialize ViewportGizmo

Source: https://fennec-hub.github.io/three-viewport-gizmo/api.html

Shows how to instantiate the ViewportGizmo by passing the camera and renderer instances. This setup enables the visual controller for camera manipulation.

```javascript
const gizmo = new ViewportGizmo(camera, renderer, { 
  placement: 'top-right', 
  animated: true 
});
```

--------------------------------

### ViewportGizmo Events

Source: https://fennec-hub.github.io/three-viewport-gizmo/api.html

Handles events triggered during user interaction with the ViewportGizmo, such as starting, changing, or ending view manipulations.

```APIDOC
## ViewportGizmo Events

### Description
Events related to camera view manipulation interactions.

### Events
- **`start`**— Triggered when a view change interaction begins.
  Occurs when:
    * Dragging starts
    * Clicking an axis initiates a view transition
- **`change`**— Triggered during view changes.
  Occurs when:
    * Dragging updates the view
    * View transition animations are in progress
    * Any camera orientation updates happen
- **`end`**— Triggered when a view change interaction ends.
  Occurs when:
    * Dragging stops
    * View transition animation completes
```

--------------------------------

### Link OrbitControls to ViewportGizmo

Source: https://fennec-hub.github.io/three-viewport-gizmo/api.html

Demonstrates how to synchronize the ViewportGizmo with OrbitControls. This allows the gizmo to reflect camera changes made by the controls and vice versa.

```javascript
const controls = new OrbitControls(camera, renderer.domElement);
gizmo.attachControls(controls);
```

--------------------------------

### ViewportGizmo Constructor

Source: https://fennec-hub.github.io/three-viewport-gizmo/api.html

Initializes a new instance of the ViewportGizmo. This controller allows for visual manipulation of a 3D camera's viewing angle.

```APIDOC
## ViewportGizmo Constructor

### Description
Initializes a new instance of the ViewportGizmo, a 3D camera orientation controller.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Constructor Signature
`constructor( camera: PerspectiveCamera | OrthographicCamera, renderer: WebGLRenderer, options?: GizmoOptions )`

### Parameters Details
- **`camera`** (PerspectiveCamera | OrthographicCamera) - Required - The camera to be controlled by the gizmo.
- **`renderer`** (WebGLRenderer) - Required - The renderer used to render the scene.
- **`options`** (GizmoOptions) - Optional - Configuration options for the gizmo.
```

--------------------------------

### Integrate ViewportGizmo with OrbitControls

Source: https://fennec-hub.github.io/three-viewport-gizmo/quickstart.html

Demonstrates how to integrate ViewportGizmo with Three.js OrbitControls. It initializes the gizmo, attaches it to controls, and includes necessary render and resize logic.

```javascript
import * as THREE from "three";
import { OrbitControls } from "three/addons/controls/OrbitControls.js";
import { ViewportGizmo } from "three-viewport-gizmo";

//... Initialize your Scene

const controls = new OrbitControls(camera, renderer.domElement);

const gizmo = new ViewportGizmo(camera, renderer);
gizo.attachControls(controls);

// Render
function animation(time) {
  //... Scene's animations and render

  gizmo.render();
}

// Resize
window.onresize = () => {
  //... Scene's resize logic

  gizmo.update();
};
```

--------------------------------

### Import ViewportGizmo using CDN

Source: https://fennec-hub.github.io/three-viewport-gizmo/quickstart.html

Imports the ViewportGizmo library directly using a CDN link. This is useful for quick testing or projects not using a module bundler.

```javascript
import * as THREE from "https://unpkg.com/three@0.173.0/build/three.module.js";
import { ViewportGizmo } from "https://cdn.jsdelivr.net/gh/taucad/three-viewport-gizmo/dist/three-viewport-gizmo.js";
```

--------------------------------

### GizmoOptions Configuration

Source: https://fennec-hub.github.io/three-viewport-gizmo/api.html

Defines the structure and parameters for configuring the ViewportGizmo instance.

```APIDOC
## Configuration Object: GizmoOptions

### Description
The GizmoOptions object is used to initialize and configure the behavior and visual style of the ViewportGizmo.

### Parameters
#### Request Body
- **container** (HTMLElement | string) - Optional - Parent container for the gizmo.
- **type** ("sphere" | "cube" | "rounded-cube") - Optional - Geometry type of the gizmo.
- **size** (number) - Optional - Size of the widget in pixels.
- **placement** (string) - Optional - Viewport position (e.g., "top-left", "bottom-right").
- **animated** (boolean) - Optional - Enables animation for view transitions.
- **speed** (number) - Optional - Animation speed multiplier.
- **background** (object) - Optional - Configuration for the background geometry.
- **font** (object) - Optional - Font settings for axis labels.

### Request Example
{
  "type": "rounded-cube",
  "size": 100,
  "placement": "top-right",
  "animated": true,
  "background": {
    "enabled": true,
    "color": "#ffffff",
    "opacity": 0.5
  }
}
```

--------------------------------

### Configure importmap for ViewportGizmo

Source: https://fennec-hub.github.io/three-viewport-gizmo/quickstart.html

Sets up an import map in HTML to alias 'three' and 'three-viewport-gizmo' for module imports. This allows cleaner import statements in your JavaScript.

```html
<script type="importmap">
  {
    "imports": {
      "three": "https://unpkg.com/three@0.173.0/build/three.module.js",
      "three/addons/": "https://unpkg.com/three@0.173.0/examples/jsm/",
      "three-viewport-gizmo": "https://cdn.jsdelivr.net/gh/taucad/three-viewport-gizmo/dist/three-viewport-gizmo.js"
    }
  }
</script>

<script type="module">
  import * as THREE from "three";
  import { ViewportGizmo } from "three-viewport-gizmo";
</script>
```

--------------------------------

### ViewportGizmo Methods

Source: https://fennec-hub.github.io/three-viewport-gizmo/api.html

Provides methods to interact with and control the ViewportGizmo, such as updating its state, rendering, and attaching external controls.

```APIDOC
## ViewportGizmo Methods

### Description
Methods available for interacting with and managing the ViewportGizmo.

### Methods
- **`set( options?: GizmoOptions ): ViewportGizmo`**
  Regenerates the gizmo with the new options.
  * **WARNING**: Not recommended for use in real-time rendering or animation loops. Provides a way to completely rebuild the gizmo with new options. Can be computationally expensive, so use sparingly.

- **`render( ): ViewportGizmo`**
  Renders the gizmo within the viewport.

- **`domUpdate( ): ViewportGizmo`**
  Updates the gizmo's DOM properties based on position and size in the document.

- **`cameraUpdate( ): ViewportGizmo`**
  Updates the gizmo's orientation to match the current camera orientation.

- **`update( controls?: boolean ): ViewportGizmo`**
  Performs a full update of the gizmo, including DOM and camera-related updates.

- **`attachControls( controls: OrbitControls ): void`**
  Links `OrbitControls` with the gizmo, managing interaction states and updates.

- **`detachControls( ): void`**
  Removes all event listeners and detaches controls if previously attached.

- **`dispose( ): void`**
  Cleans up all resources, including geometries, materials, textures, and event listeners.
```

--------------------------------

### Configuration API

Source: https://fennec-hub.github.io/three-viewport-gizmo/api.html

Endpoints for customizing the visual properties of the gizmo, including corner indicators, edge settings, and axis-specific configurations.

```APIDOC
## CONFIGURATION OPTIONS

### Description
Configures the visual appearance and interaction behavior of the Viewport Gizmo components.

### Parameters
#### Corner Indicators
- **opacity** (number) - Optional - Sets the opacity of corner indicators.
- **scale** (number) - Optional - Sets the scale multiplier for corner indicators.
- **radius** (number) - Optional - Sets the radius of corner indicators.
- **smoothness** (number) - Optional - Controls the smoothness of corner indicators.

#### Edge Configuration
- **edges.enabled** (boolean) - Optional - Enables or disables edge indicators.
- **edges.color** (ColorRepresentation) - Optional - Sets the base color of edge indicators.

#### Axis Configuration
- **axis** (object) - Optional - Configuration for x, y, z, nx, ny, nz axes.
- **axis.enabled** (boolean) - Optional - Toggles axis visibility.
- **axis.label** (string) - Optional - Custom text label for the axis.

### Request Example
{
  "opacity": 0.8,
  "edges": { "enabled": true, "color": "#ffffff" },
  "x": { "enabled": true, "label": "Right" }
}
```

--------------------------------

### Define ViewportGizmo Configuration Types

Source: https://fennec-hub.github.io/three-viewport-gizmo/api.html

Defines the GizmoOptions and GizmoAxisOptions types, which provide a comprehensive schema for customizing the gizmo's visual properties, positioning, and interactive states.

```typescript
type GizmoOptions = {
  container?: HTMLElement | string;
  type?: "sphere" | "cube" | "rounded-cube";
  size?: number;
  placement?: "top-left" | "top-center" | "top-right" | "center-left" | "center-center" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right";
  offset?: { left?: number; top?: number; right?: number; bottom?: number; };
  animated?: boolean;
  speed?: number;
  resolution?: number;
  lineWidth?: number;
  id?: string;
  className?: string;
  font?: { family?: string; weight?: string | number; };
  background?: { enabled?: boolean; color?: ColorRepresentation; opacity?: number; hover?: { color?: ColorRepresentation; opacity?: number; }; };
  corners?: { enabled?: boolean; color?: ColorRepresentation; opacity?: number; scale?: number; radius?: number; smoothness?: number; hover?: { color?: ColorRepresentation; opacity?: number; scale?: number; }; };
  edges?: { enabled?: boolean; color?: ColorRepresentation; opacity?: number; scale?: number; radius?: number; smoothness?: number; hover?: { color?: ColorRepresentation; opacity?: number; scale?: number; }; };
  radius?: number;
  smoothness?: number;
  x?: GizmoAxisOptions;
  y?: GizmoAxisOptions;
  z?: GizmoAxisOptions;
  nx?: GizmoAxisOptions;
  ny?: GizmoAxisOptions;
  nz?: GizmoAxisOptions;
  right?: GizmoAxisOptions;
  top?: GizmoAxisOptions;
  front?: GizmoAxisOptions;
  left?: GizmoAxisOptions;
  bottom?: GizmoAxisOptions;
  back?: GizmoAxisOptions;
};

type GizmoAxisOptions = {
  enabled?: boolean;
  label?: string;
  opacity?: number;
  scale?: number;
  line?: boolean;
  color?: ColorRepresentation;
  labelColor?: ColorRepresentation;
  border?: { size: number; color: ColorRepresentation; };
  hover?: { color?: ColorRepresentation; labelColor?: ColorRepresentation; opacity?: number; scale?: number; border?: { size: number; color: ColorRepresentation; }; };
};
```

--------------------------------

### ViewportGizmo Properties

Source: https://fennec-hub.github.io/three-viewport-gizmo/api.html

Manages the state and behavior of the ViewportGizmo, including its enabled status, camera target, and animation settings.

```APIDOC
## ViewportGizmo Properties

### Description
Properties that control the behavior and state of the ViewportGizmo.

### Properties
- **`enabled`** (`boolean`) - Specifies if the gizmo is active and responsive to user input.
- **`camera`** (`OrthographicCamera | PerspectiveCamera`) - The camera controlled by this gizmo.
- **`target`** (`Vector3`) - The point around which the camera rotates.
- **`placement`** (`boolean`) - Sets and updates the placement of the gizmo relative to its container.
- **`animated`** (`boolean`) - Specifies if view changes should be animated.
- **`speed`** (`number`) - Controls animation speed, where higher values result in faster animations.
- **`animating`** (`boolean` - readonly) - `True` if the gizmo is currently animating view changes.
```

--------------------------------

### Update Gizmo in Render Loop

Source: https://fennec-hub.github.io/three-viewport-gizmo/api.html

Illustrates the standard usage of the update method within a requestAnimationFrame loop to ensure the gizmo stays synchronized with the camera state.

```javascript
function animate() {
  requestAnimationFrame(animate);
  gizmo.update();
  renderer.render(scene, camera);
}
```

--------------------------------

### ViewportGizmoEventMap

Source: https://fennec-hub.github.io/three-viewport-gizmo/api.html

Describes the custom events emitted by the ViewportGizmo during user interactions.

```APIDOC
## EVENT MAP

### Description
Defines events emitted by the ViewportGizmo during interaction cycles.

### Events
- **start**: Triggered when a view change interaction begins.
- **change**: Triggered during view changes.
- **end**: Triggered when a view change interaction ends.

### Response Example
{
  "event": "start",
  "target": "ViewportGizmo"
}
```
Tokens:
Raw