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 fragment IDs of specific object or entire scene.

To make sure the method call is synchronous (i.e., it returns after all fragments have been enumerated), always wait until 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 object whose fragments should be enumerated. If undefined, the enumeration includes all scene fragments.
Source:
Throws:

Exception if no Model is loaded.

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 IDs of leaf objects in the scene.

To make sure the method call is synchronous (i.e., it returns after all objects have been enumerated), always wait until the object tree has been loaded.

Parameters:
Name Type Attributes Description
callback NodeCallback

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

ID of the parent object whose children should be enumerated. If undefined, the enumeration includes all leaf objects.
Source:
Throws:

Exception if no Model is loaded.

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 IDs of objects in the scene.

To make sure the method call is synchronous (i.e., it returns after all objects have been enumerated), always wait until the object tree has been loaded.

Parameters:
Name Type Attributes Description
callback NodeCallback

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

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

Exception if no Model is loaded.

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);
  }
});

listFragments(parentIdopt, nullable) → {Promise.<Array.<number>>}

Lists fragments IDs of specific scene object. Should be called after the object tree has been loaded.

Parameters:
Name Type Attributes Description
parentId number <optional>
<nullable>

ID of the parent object whose fragments should be listed. If undefined, the list will include all fragment IDs.
Source:
Example

Using async/await 

viewer.addEventListener(Autodesk.Viewing.OBJECT_TREE_CREATED_EVENT, async function() {
  const ids = await utils.listFragments();
  console.log('Fragment IDs', ids);
});

listLeafNodes(parentIdopt, nullable) → {Promise.<Array.<number>>}

Lists IDs of leaf objects in the scene.

Parameters:
Name Type Attributes Description
parentId number <optional>
<nullable>

ID of the parent object whose children should be listed. If undefined, the list will include all leaf object IDs.
Source:
Example

Using async/await 

viewer.addEventListener(Autodesk.Viewing.OBJECT_TREE_CREATED_EVENT, async function() {
  const ids = await utils.listLeafNodes();
  console.log('Leaf object IDs', ids);
});

listNodes(parentIdopt, nullable) → {Promise.<Array.<number>>}

Lists IDs of objects in the scene.

Parameters:
Name Type Attributes Description
parentId number <optional>
<nullable>

ID of the parent object whose children should be listed. If undefined, the list will include all scene object IDs.
Source:
Example

Using async/await 

viewer.addEventListener(Autodesk.Viewing.OBJECT_TREE_CREATED_EVENT, async function() {
  const ids = await utils.listNodes();
  console.log('Object IDs', ids);
});

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');