Import and using viewer library

The the main library that contains all the logic of the 3D Viewer and Renderer is tangl-viewer.

Dependencies

Library does not include the dependent three.js library for a more compact size. You also need to install it explicitly.

The viewer works with version three.js 0.158 and requires it to be included in the project dependencies in packages.json:

//packages.json

"dependencies": {
    ...
    "three": "^0.161.0",
    ...
},

Import

Download libraries and put in dependencies in package.json:

npm i three@latest
npm i tangl-viewer

The library contains two assemblies exports two basic access points:

• Import for use in a web browser:

import * from "tangl-viewer"

• Import for use in Node.js on the server:

import * from "tangl-viewer/cjs"

The assembly intended for use in Node.js does not contain renderer or other classes intended solely for use in a web browser.

Creating managers

The library contains classes as well as a viewers store object.

All objects can be imported anywhere in the code:

//managers.ts

import {MetaManager, SceneManager, viewerStore} from "tangl-viewer";

export const sceneManager = new SceneManager()
export const metaManager = new MetaManager()
export const renderManager = viewerStore.createRenderManager("default", sceneManager,metaManager)

If no servers are specified, managers will access Tangl cloud servers by default. If Tangl is deployed on-premise, server URLs must be specified explicitly:

//managers.ts

import {MetaManager, SceneManager, viewerStore} from "tangl-viewer";

export const sceneManager = new SceneManager().setServer(env.VITE_TANGL_SERVER)
export const metaManager = new MetaManager().setServer(env.VITE_TANGL_SERVER, env.VITE_TANGL_CACHE_SERVER)
export const renderManager = viewerStore.createRenderManager("default", sceneManager,metaManager)

It is also necessary to install authorization tokens in managers to access Tangl cloud servers, if they are used. Authorization tokens can be set anytime and anywhere:

sceneManager.setToken(token);
metaManager.setToken(token);

If you want to use the lazy properties loading mode, you should set the MetaManager.useCache parameter:

metaManager.useCache = true;

Internationalization and localization

The viewer uses the i18next internationalization system. To activate it you need to pass an initialized 18next object into the viewer. The viewer will add its multilingual locales to it:

import i18next from "i18next";
import {Ui} from "tangl-viewer";
i18next.init({
  //i18next init settings
})
Ui.setI18next(i18next)

If your application does not have a multi-language system, you may not pass the i18next object. In this case the viewer will create it for itself, set the current Russian locale and use it:

import {Ui} from "tangl-viewer";
Ui.setI18next()

The viewer sets locales to a separate namespace "tgv".

Append viewer and additional UI components to DOM tree

To embed the viewer in the DOM tree, it is necessary to have a container with the necessary id of the DOM element in which the viewer and its UI will be embedded.

Id must be supplied during RenderManager initialization:

//view component file

import {renderManager, sceneManager, metaManager} from "../managers";

...

renderManager?.init("viewer"); //will append to #viewer DOM element

To embed UI components MetaTree (model tree panel) and PropsTree (selected element properties panel), you also need to have containers in the markup with the desired Id:

//view component file

import {renderManager, sceneManager, metaManager} from "../managers";
import {appendPropsTree, appendToolbar, PropsTreeContext} from "tangl-viewer-ui-vue";
import {Ui} from "tangl-viewer"
...
renderManager?.init("viewer"); //will append to #viewer HTML element

let propsTreeComponent: Ui.PropsTreeContext;
let metaTreeComponent: Ui.MetaTreeContext;

propsTreeComponent = Ui.appendPropsTree("tgv-propstree", metaManager) //will append to #tgv-propstree DOM element
metaTreeComponent = Ui.appendMetaTree("tgv-metatree", metaManager, {
  selected: onMetaSelected //callback on select node in tree
}) //will append to #tgv-treetree DOM element

When inserting a component, it is possible to specify an event handler for selecting a node in the tree. It can be used to synchronize selection of elements in the model tree and selection of elements in the viewer.

onMetaSelected(e: { geomNums: number[], elNums: number[] }) {
  sceneManager.updateSelection(e.elNums, false);
},

CSS styles must also be imported for the UI components to display properly:

//style.scss
@import "../node_modules/tangl-viewer-/dist/style.css" layer(viewer)

Connecting additional extensions

After initializing RenaderManager, it is recommended to activate the standard viewer extensions included with it:

//view component file
...
import {
	CoordinatesExtension,
	CropExtension, FlyControllerExtension,
	GeneralModeExtension, MeasureExtension,
    OrbitControllerExtension,
	VisibilityExtension
} from "tangl-viewer";
...
renderManager?.init("viewer"); //will append to #viewer HTML element
...
//built-in extensions
renderManager.extMan.addExtension(OrbitControllerExtension)
renderManager.extMan.addExtension(FlyControllerExtension)
renderManager.extMan.addExtension(GeneralModeExtension)
renderManager.extMan.addExtension(CropExtension)
renderManager.extMan.addExtension(VisibilityExtension)
renderManager.extMan.addExtension(MeasureExtension)
renderManager.extMan.addExtension(CoordinatesExtension)

Events

To track an item selection event in the viewer, you need to subscribe to the corresponding event where you can send information about the selected item to its properties component using PropsTreeContext:

sceneManager.addEventListener(SceneEvents.Selected, onSceneSelected)

onSceneSelected(e: ElementsSelectedEvent) {
  propsTreeComponent.fetchPropsByNumbers(sceneManager.selElNums[0]);
}

Loading models

You can load a model into the viewer managers for display in the scene by using the managers functions on the list of version GUIDs:

sceneManager.load((ids as string[]).join(";"))
metaManager.load(ids)

Demo

See an example of how to use the libraries:

Basic Demo application:

https://github.com/tangl-services/tangl-dev/tree/main/tangl-demo-basic

Extended demo application:

https://github.com/tangl-services/tangl-dev/tree/main/tangl-demo-playground