NgtsGizmoHelper

Preview

canvas.ts

import { ChangeDetectionStrategy, Component } from '@angular/core';
import { SobaWrapper } from '@soba/wrapper.ts';
import { NgtCanvas, provideNgtRenderer } from 'angular-three/dom';
import { SceneGraph } from './scene-graph';

@Component({
    selector: 'app-gizmo-helper',
    template: `
        <ngt-canvas [camera]="{ position: [3, 3, 3], fov: 50 }">
            <app-soba-wrapper *canvasContent>
                <app-scene-graph />
            </app-soba-wrapper>
        </ngt-canvas>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: { class: 'gizmo-helper-demo relative block h-full' },
    imports: [NgtCanvas, SobaWrapper, SceneGraph],
})
export default class GizmoHelper {
    static clientProviders = [provideNgtRenderer()];
}

scene-graph.ts

import { ChangeDetectionStrategy, Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { NgtArgs } from 'angular-three';
import { NgtsGizmoHelper, NgtsGizmoViewcube } from 'angular-three-soba/gizmos';

@Component({
    selector: 'app-scene-graph',
    template: `
        <ngt-mesh>
            <ngt-box-geometry *args="[1.5, 1.5, 1.5]" />
            <ngt-mesh-normal-material />
        </ngt-mesh>

        <ngts-gizmo-helper [options]="{ alignment: 'bottom-right', margin: [80, 80] }">
            <ngts-gizmo-viewcube *gizmoHelperContent />
        </ngts-gizmo-helper>
    `,
    schemas: [CUSTOM_ELEMENTS_SCHEMA],
    changeDetection: ChangeDetectionStrategy.OnPush,
    imports: [NgtArgs, NgtsGizmoHelper, NgtsGizmoViewcube],
})
export class SceneGraph {}

NgtsGizmoHelper displays an orientation gizmo helper in a corner of the viewport. It renders in a separate portal with its own orthographic camera and allows users to click on axes to animate the camera to predefined views.

Usage

import { NgtsGizmoHelper, NgtsGizmoViewcube, NgtsGizmoViewport } from 'angular-three-soba/gizmos';

<ngts-gizmo-helper [options]="{ alignment: 'bottom-right', margin: [80, 80] }">
  <ng-template gizmoHelperContent>
    <ngts-gizmo-viewport />
  </ng-template>
</ngts-gizmo-helper>

NgtsGizmoViewcube

A 3D cube-style orientation gizmo with labeled faces (Front, Back, Left, Right, Top, Bottom). Clickable faces, edges, and corners allow users to orient the camera to standard or diagonal views. Must be used inside NgtsGizmoHelper.

Options

Property	Type	Default	Description
font	string	'20px Inter var, Arial, sans-serif'	CSS font specification for face labels
opacity	number	1	Opacity of the cube faces
color	string	'#f0f0f0'	Background color of the cube faces
hoverColor	string	'#999'	Color when a face is hovered
textColor	string	'black'	Color of the face label text
strokeColor	string	'black'	Color of the face border stroke
faces	string[]	['Right', 'Left', 'Top', 'Bottom', 'Front', 'Back']	Labels for each face

Outputs

Output	Description
click	Emits when a face/edge/corner is clicked

<ngts-gizmo-helper>
  <ng-template gizmoHelperContent>
    <ngts-gizmo-viewcube [options]="{ color: '#fff', hoverColor: '#ccc' }" />
  </ng-template>
</ngts-gizmo-helper>

NgtsGizmoViewport

A viewport-style gizmo with colored axes (X, Y, Z) and interactive heads. Clicking on axis heads animates the camera to the corresponding view direction. Must be used inside NgtsGizmoHelper.

Options

Property	Type	Default	Description
axisColors	[string, string, string]	['#ff2060', '#20df80', '#2080ff']	Colors for the X, Y, and Z axes
axisScale	[number, number, number]	undefined	Scale of the axis lines [x, y, z]
labels	[string, string, string]	['X', 'Y', 'Z']	Labels for the X, Y, and Z axis heads
axisHeadScale	number	1	Scale factor for the axis head sprites
labelColor	string	'#000'	Color of the axis labels
hideNegativeAxes	boolean	false	Whether to hide the negative axis heads
hideAxisHeads	boolean	false	Whether to hide all axis heads
disabled	boolean	false	Whether the gizmo is non-interactive
font	string	'18px Inter var, Arial, sans-serif'	CSS font specification for axis labels

Outputs

Output	Description
click	Emits when an axis is clicked

<ngts-gizmo-helper>
  <ng-template gizmoHelperContent>
    <ngts-gizmo-viewport [options]="{ axisColors: ['red', 'green', 'blue'] }" />
  </ng-template>
</ngts-gizmo-helper>

Outputs

name	type	description
update	void	Emits when the camera animation updates.

Options

Properties

name	type	description
alignment	'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'	Position of the gizmo in the viewport. Default: 'bottom-right'
margin	[number, number]	Margin from the edge of the viewport in pixels [x, y]. Default: [80, 80]
renderPriority	number	Render priority for the gizmo portal. Default: 1
autoClear	boolean	Whether to auto-clear the renderer before rendering. Default: undefined