Utilities

Utilities

new Utilities(viewer)

Initializes Utilities with existing instance of Viewer3D.

Parameters:
Name Type Description
viewer Viewer3D

Forge viewer.
Source:

Methods

(static) Initialize(container, getAccessToken) → {Promise.<Utilities>}

Initializes new instance of Utilities, including the initialization of the underlying Viewer3D.

Parameters:
Name Type Description
container HTMLElement

Target container for the viewer canvas.
getAccessToken AccessTokenRequest

Function that will be called by the viewer whenever a new access token is required.
Source:
Examples

Using Promises 

function getAccessToken(callback) {
  fetch('/api/forge/auth/token')
    .then(resp => resp.json())
    .then(json => callback(json.access_token, json.expires_in));
}
Autodesk.Viewing.Utilities.Initialize(document.getElementById('viewer'), getAccessToken)
  .then(utils => console.log(utils));

Using Async/Await 

async function getAccessToken(callback) {
  const resp = await fetch('/api/forge/auth/token');
  const json = await resp.json();
  callback(json.access_token, json.expires_in);
}
async function init() {
  const utils = await Autodesk.Viewing.Utilities.Initialize(document.getElementById('viewer'), getAccessToken);
  console.log(utils);
}
init();

addCustomMesh(mesh, overlayopt)

Inserts custom Mesh into overlay scene of given name. An overlay scene is always rendered after the main scene with the Forge Viewer model.

Parameters:
Name Type Attributes Default Description
mesh THREE.Mesh

Custom Mesh.
overlay string <optional>
 'UtilitiesOverlay'

Name of the overlay scene.
Source:
Example
const geometry = new THREE.SphereGeometry(10, 8, 8);
const material = new THREE.MeshBasicMaterial({ color: 0x336699 });
const mesh = new THREE.Mesh(geometry, material);
mesh.position.x = 1.0; mesh.position.y = 2.0; mesh.position.z = 3.0;
utils.addCustomMesh(mesh, 'myOverlay');

enumerateFragments(callback, parentopt, nullable)

Enumerates fragments of specific node or entire scene. Can only be called after the object tree has been loaded.

Parameters:
Name Type Attributes Description
callback FragmentCallback

Function called for each fragment.
parent number <optional>
<nullable>

ID of the parent node whose fragments should be enumerated. If undefined, the enumeration includes all scene fragments.
Source:
Throws:

Exception when the object tree is not yet available.

Example
viewer.addEventListener(Autodesk.Viewing.OBJECT_TREE_CREATED_EVENT, function() {
  try {
    utils.enumerateFragments(function(id) {
      console.log('Found fragment', id);
    });
  } catch(err) {
    console.error('Could not enumerate fragments', err);
  }
});

enumerateLeafNodes(callback, parentopt, nullable)

Enumerates leaf nodes in the viewer scene. Can only be called after the object tree has been loaded.

Parameters:
Name Type Attributes Description
callback NodeCallback

Function called for each node.
parent number <optional>
<nullable>

ID of the parent node whose children should be enumerated. If undefined, the enumeration includes all scene nodes.
Source:
Throws:

Exception when the object tree is not yet available.

Example
viewer.addEventListener(Autodesk.Viewing.OBJECT_TREE_CREATED_EVENT, function() {
  try {
    utils.enumerateLeafNodes(function(id) {
      console.log('Found leaf node', id);
    });
  } catch(err) {
    console.error('Could not enumerate nodes', err);
  }
});

enumerateNodes(callback, parentopt, nullable)

Enumerates all nodes in the viewer scene. Can only be called after the object tree has been loaded.

Parameters:
Name Type Attributes Description
callback NodeCallback

Function called for each node.
parent number <optional>
<nullable>

ID of the parent node whose children should be enumerated. If undefined, the enumeration includes all scene nodes.
Source:
Throws:

Exception when the object tree is not yet available.

Example
viewer.addEventListener(Autodesk.Viewing.OBJECT_TREE_CREATED_EVENT, function() {
  try {
    utils.enumerateNodes(function(id) {
      console.log('Found node', id);
    });
  } catch(err) {
    console.error('Could not enumerate nodes', err);
  }
});

getFragmentBounds(fragId) → {THREE.Box3}

Gets world bounding box of scene fragment.

Parameters:
Name Type Description
fragId number

Fragment ID.
Source:
Throws:

Exception when the fragments are not yet available.

Example
viewer.addEventListener(Autodesk.Viewing.GEOMETRY_LOADED_EVENT, function() {
  try {
    const bounds = utils.getFragmentBounds(1);
    console.log('Fragment bounds', bounds);
  } catch(err) {
    console.error('Could not retrieve fragment bounds', err);
  }
});

getFragmentTransform(fragId) → {THREE.Matrix4}

Gets transformation matrix of scene fragment.

Parameters:
Name Type Description
fragId number

Fragment ID.
Source:
Throws:

Exception when the fragments are not yet available.

Example
viewer.addEventListener(Autodesk.Viewing.GEOMETRY_LOADED_EVENT, function() {
  try {
    const transform = utils.getFragmentTransform(1);
    console.log('Fragment transform', transform);
  } catch(err) {
    console.error('Could not retrieve fragment transform', err);
  }
});

load(documentUrn, viewableIdopt) → {Promise.<Viewable>}

Loads Viewable into the viewer.

Parameters:
Name Type Attributes Default Description
documentUrn string

Base64-encoded identifier of the document.
viewableId string | number <optional>
 0

Optional GUID (string) or index (number) of the viewable within the document.
Source:
Example
async function loadDocument(urn) {
  const viewable = await utils.load(urn);
  console.log('Loaded viewable', viewable.data.id);
}

rayCast(x, y) → {Array.<Intersection>}

Finds all scene objects on specific X,Y position on the canvas.

Parameters:
Name Type Description
x number

X-coordinate, i.e., horizontal distance (in pixels) from the left border of the canvas.
y number

Y-coordinate, i.e., vertical distance (in pixels) from the top border of the canvas.
Source:
Example
document.getElementById('viewer').addEventListener('click', function(ev) {
  const bounds = ev.target.getBoundingClientRect();
  const intersections = utils.rayCast(ev.clientX - bounds.left, ev.clientY - bounds.top);
  if (intersections.length > 0) {
    console.log('hit', intersections[0]);
  } else {
    console.log('miss');
  }
});

removeCustomMesh(mesh, overlayopt)

Removes custom Mesh from overlay scene of given name. An overlay scene is always rendered after the main scene with the Forge Viewer model.

Parameters:
Name Type Attributes Default Description
mesh THREE.Mesh

Mesh to be removed.
overlay string <optional>
 'UtilitiesOverlay'

Name of the overlay scene.
Source:
Example
// after adding a mesh using addCustomMesh
utils.removeCustomMesh(mesh, 'myOverlay');