Procore BIM Web Viewer: Integrator Documentation

Getting started

Installation from NPM (recommended)

The Procore BIM Web Viewer is available as a module on npm as @procore/bim-webviewer-sdk.

To install it, open a terminal window in your project folder and run:

npm install @procore/bim-webviewer-sdk

Installation from a CDN

Though not recommended for production use, if you just want to prototype something you can use a tool like unpkg to get the module onto a page without the overhead of a build-system. Note we do not control unpkg and do not otherwise host the package on a publicly available CDN with uptime guarantees.

<script src="https://unpkg.com/@procore/bim-webviewer-sdk"></script>

Installation by Saving the File

If you prefer not to use npm, you can download the latest version of the code here: https://unpkg.com/@procore/bim-webviewer-sdk

If you would like a specific version you can declare that version in the url like so: https://unpkg.com/@procore/bim-webviewer-sdk@4.0.0

Load the Module with a Bundler (recommended)

If you’re using a bundling system with import (recommended):

import * as ProcoreBim from '@procore/bim-webviewer-sdk';

Load the Module Manually

If you’re managing script loading manually:

<!-- This will instantiate window.ProcoreBim -->
<script src="path/to/Procore.Bim.Webviewer.js"></script>

Instantiate and Start the Viewer

const viewer = new ProcoreBim.Webviewer(options);
viewer.start();

See the Options section for more detail on the options object.

Background Color

The viewer does not render a background or color. You may set your own background color with CSS on any parent element that contains the viewer for that background color to be displayed.

API Introduction

When the Webviewer SDK is loaded and parsed on your page, a new global object is added to your window with the key ProcoreBim. ProcoreBim contains a mix of both static and non static methods and are generally grouped into namespaces to indicate primary functionality.

ProcoreBim Namespaces

Webviewer Namespaces

When you create a new instance of Webviewer, an object is returned that allows you to act on the model and camera data. Acting on these methods is done through dot notation. Some methods belong to a sub namespace, and some methods do not.

const viewer = new ProcoreBim.Webviewer(options);
viewer.start();

The Webviewer has been instanced and we have invoked the start method which does not belong to a namespace to start initializing the model viewer.

viewer.camera.setPosition(1, 10, -1);

Here we invoke setPosition method from the camera namespace to set the camera position in the model viewer.

The Cache namespace contains static methods and has the following pattern:

ProcoreBim.Cache.{method_name}

Complete Example

const viewer = new ProcoreBim.Webviewer(options);

// Starts the viewer, must be called.
// `start` does not belong to a namespace.
viewer.start();

// Gets the camera direction, `getCameraDirection()` belongs to
// the `camera` namespace.
var cameraDirection = viewer.camera.getCameraDirection();

// Checks if the model is cached, `hasModel` returns a promise
// and belongs to the `Cache` namespace.
ProcoreBim.Cache.hasModel({
  meshUrl: 'samples/vortex.mesh',
  meshnodeUrl: 'samples/vortex.meshnode',
  nodeUrl: 'samples/vortex.node',
}).then(function (isCached) {
  console.log(isCached);
});

General API

Starting the Webviewer

start();

Description

Entry point to the Webviewer and starts rendering. This method must be called.

Parameters

None

Returns

undefined

Namespace

None

Terminating the Webviewer

terminate();

Description

Stops rendering, frees memory, and removes webviewer from parent element.

Parameters

None

Returns

undefined

Namespace

None

Api Namespace

Get Object Name

getNamesForObjects(objectIds);

Description

Return an array of object names with the given id.

Parameters

Returns

{
  id: number,
  value: string
}

Namespace

Api

Filter Objects

filterObjects(objectIds);

Description

Lists objects for the loaded model given a filter. The schema for the filter parameter is defined as

export const ObjectFilterSchema: JSONSchemaType<ObjectFilter> = {
  type: 'object',
  properties: {
    filterField: {
      type: 'string',
      enum: ['name'],
    },
    filterValue: {
      type: 'string',
    },
  },
  required: ['filterField', 'filterValue'],
};

Currently, we only support a filter field of name.

Example usage:

const response = await this.viewer.api.filterObjects({
  filterField: 'name',
  filterValue: 'wall',
});

Parameters

Returns

Response Object

Namespace

Api

Camera Namespace

Get Camera Position

getPosition();

Description

Retrieves the active camera position.

Parameters

None

Returns

Promise<{
  x: Number, y: Number, z: Number
}>

Namespace

Camera

Set Camera Position

setPosition(x, y, z);

Description

Sets the camera position.

Parameters

Returns

Promise<{
  position: {x: Number, y: Number, z: Number},
  direction: {x: Number, y: Number, z: Number}
}>

Namespace

Camera

Get Camera Direction

getCameraDirection();

Description

Retrieves the direction vector for the active camera target.

Parameters

None

Returns

Promise<{
  x: Number, y: Number, z: Number
}>

Namespace

Camera

Get Camera Look At

getLookAt();

Description

Gets the camera target.

Parameters

None

Returns

Promise<{
  x: Number, y: Number, z: Number
}>

Set Camera Look At

setLookAt(x, y, z);

Description

Sets the camera target.

Parameters

Returns

Promise<{
  position: {x: Number, y: Number, z: Number},
  direction: {x: Number, y: Number, z: Number}
}>

Namespace

Camera

Get Screen Position

getScreenPosition(x, y, z);

Description

Take position in world space and convert it to screen space

Parameters

Returns

Promise<{
  x: Number, y: Number, z: Number
}>

Namespace

Camera

Get Snapshot

getSnapshot(color);

Description

Force download the current render view into a png.

Parameters

Returns

Promise<void>

Namespace

Camera

Get Snapshot Data URL

getSnapshotDataUrl(params);

Description

Returns a data url of an image produced by the current render view.

Parameters

Returns

The canvas as a base64-encoded image.

Promise<string>

Namespace

Camera

Set Camera From BCF Camera

setBcfCamera(bcfCamera, applyOffset);

Description

Sets the camera position and direction from BCF camera data. See Orthogonal Camera or Perspective Camera

NOTE: You should always pass true for the applyOffset argument. If you pass nothing or false then it is probably not what you want. It will soon be removed and that will be the default as it is an implementation detail that need not be exposed. See migration guide for v7 to v8 for more details.

Parameters

Returns

Promise<{
  perspective_camera: {
    camera_view_point:  {x: Number, y: Number, z: Number},
    camera_direction:  {x: Number, y: Number, z: Number},
    camera_up_vector:  {x: Number, y: Number, z: Number},
    field_of_view: Number,
    target_distance: Number
  }
}>

Namespace

Camera

Get BCF Camera From Camera

getBcfCamera();

Description

Retrieves a BCF perspective camera.

Parameters

None

Returns

Promise<{
  perspective_camera: {
    camera_view_point:  {x: Number, y: Number, z: Number},
    camera_direction:  {x: Number, y: Number, z: Number},
    camera_up_vector:  {x: Number, y: Number, z: Number},
    field_of_view: Number,
    target_distance: Number
  }
}>

Namespace

Camera

Navigation to the home viewpoint

navToHomeView();

Description

Navigation to the home viewpoint if bcfCamera option has been set. If not, zooms to fit the axis-aligned bounding box of the entire model with space junk eliminated (see zoomToGlobal).

Parameters

None

Returns

Promise<void>

Namespace

Camera

Zoom to Objects

zoomToObjects(objectIds);

Description

Moves camera from current position to fit the axis-aligned bounding box of the node or set of objects.

Parameters

Returns

Promise<void>

Namespace

Camera

Zoom to Fit a Bounding Box

zoomToBoundingBox(bbox);

Description

Moves camera to fit the specified axis-aligned bounding box.

Parameters

Returns

Promise<void>

Namespace

Camera

Zoom to Selection

zoomToSelection();

Description

Moves camera from current position to fit the axis-aligned bounding box of the current selection.

Parameters

None

Returns

Promise<void>

Namespace

Camera

Zoom to Global

zoomToGlobal();

Description

Moves camera to fit the axis-aligned bounding box of the entire model. Does not take into account current camera position, i.e. will always give you the same view regardless of where the camera is currently.

As of v5.1.0, zoomToGlobal will zoom to the “refined global bounding box” in which “space junk” has been eliminated. Space junk is loosely defined as objects which are far from all other objects in the model and distort the global bounding box dramatically.

Performance Note: the execution time for eliminating space junk scales with the number of meshnodes in the model. Mostly this cost is incurred at load time, but will be incurred the first time zoomToGlobal is called if a bcfCamera option was provided.

Parameters

None

Returns

Promise<void>

Namespace

Camera

Set Euler Angles

setEulerAngles(x, y, z);

Description

Sets the camera with euler angles, yaw, pitch and roll

Parameters

Returns

Promise<void>

Namespace

Camera

Set Markup

setMarkup(markupData, fov);

Description

This is a deprecated method. Use markup.setRedlines, which has the same signature.

Set Pose

setPose(params);

Description

Sets the position and orientation of a 3D camera based on a given pose.

Parameters

Params Object

The params object has the following structure:

If pose is an object, it should have the following structure:

If pose is a string, it should be one of the following values: “top”, “bottom”, “front”, “back”, “left”, “right”

Example

camera.setPose({
  pose: {
    position: { x: 1, y: 2, z: 3 },
    lookAt: { x: 4, y: 5, z: 6 },
  },
  cameraUp: { x: 0, y: 1, z: 0 },
});

In this example, the setPose method sets the camera’s position to (1, 2, 3), sets the camera to look at the point (4, 5, 6), and sets the camera’s up direction to point in the positive y-direction.

camera.setPose({
  pose: "top",
});

In this example, the setPose method sets the camera to a predefined “top” pose, which sets the position of the camera above the model and looks down at it.

Returns

Promise<void>

Namespace

Camera

DOM Namespace

Add Panel

addPanel(domElement);

Description

Adds a container div to the Webviewer canvas and appends Element to it.

Parameters

Returns

boolean

Namespace

Dom

Remove Panel

removePanel(domElement);

Description

Removes the container div from the viewer which contains the argument Element.

Parameters

Returns

boolean

Namespace

Dom

Events Namespace

Add Event

addEventListener(eventName, callback);

Description

Executes a callback when an internal viewer event occurs.

The callback parameter is a third party defined function to be executed when the event fires. Depending on the event, the callback function may return undefined, or data. This data may be a number, string, or a JavaScript object.

Parameters

Returns

void

Namespace

Events

Remove Event

removeEventListener(eventName, callback);

Description

Removes a callback from an internal viewer event, if it is identical to a callback that was already added.

Parameters

Returns

void

Namespace

Events

Dispatch Event

dispatchEvent(eventName, callback);

Description

Manually dispatches an event

Parameters

Returns

void

Namespace

Events

Event Names

The following event names are available to notify third party code of changes in the viewer.

Complete Example

const viewer = new ProcoreBim.Webviewer(options);

viewer.events.addEventListener('appResize', (data) => {
  // Called when the window resizes and returns an object with properties
  // `offsetHeight`, `offsetWidth`, `offsetLeft`, `offsetTop`.
  console.log(data.offsetHeight);
});

viewer.events.addEventListener('bcfCameraSet', () => {
  // Called when the camera has been set, does not return any data.
});

viewer.start();

animate

Fires at the end of the animation loop. Returns an object containing the property stage to indicate the stage the renderer is in to render the scene. renderIdle indicates that the scene has been fully rendered and the renderer is no longer rendering any objects. renderStart indicates the start of rendering a scene. renderProgress is a state after renderStart and indicates the renderer is still rendering the scene. Finally, renderComplete indicates that all the objects have been rendered.

Data Properties

appResize

Fires when the document view (window) has been resized.

Data Properties

appStart

Fires after start() is called on the Webviewer instance.

bcfCameraSet

Fires after a BCF Camera has been set.

cameraUpdated

Fires after the camera direction or camera position has been modified.

canvasReady

Fires after the rendering canvas has been created.

coachmarkHyperlinkClicked

Fires when the coachmark indicator has been cleared. The coachmark will appear in the upper right hand corner of the webviewer appear when:

• objects are hidden
• section planes are applied
• a field of view has been applied other than the default field of view

When the coachmark is cleared, this event will fire with a value indicating which type of coachmark was cleared:

• "hidden"
• "section"
• "fov"

doubleClick

Fires after a double click occurs on the webviewer container element. Returns a MouseEvent object.

downloadComplete

Fires after all download requests for the model have been completed. This event will still fire even if the model is cached.

downloadProgress

Fires periodically to report progress on how much of the model has been downloaded.

Data Properties

downloadStart

Fires before requests are made to download the model.

drawingNavigated

Fires when the 2D Navigation overlay is used to navigate the model. Specifically, this fires after a location and direction have been chosen on the floor plan and the overlay is dismissed.

drawingMiniClick

Fires when the 2D Navigation mini map was clicked on.

floorPlan

Fires when the 2D Navigation overlay is interacted with.

Data Properties

floorPlanNavigateAndClose

Updates the camera position and direction in addition to dismissing the 2D floor plan overlay.

Parameters

floorPlanPoint

Returns the corresponding point on the 2D floor plan overlay from a point in 3D model space.

Parameters

Example

const viewer = new ProcoreBim.Webviewer(options);

let floorPlanNavigateAndClose = null;

viewer.events.addEventListener('floorPlan', (data) => {
  // Executed when the 2D floor plan overlay is interacted with.
  if (data.type === 'open') {
    // Your application might need to know when the 2D floor plan overlay is `open` and keep a reference to
    // floorPlanNavigateAndClose
    floorPlanNavigateAndClose = data.floorPlanNavigateAndClose;
  }
});
viewer.start();

// Perhaps your application places markers that represent 3D positions on the 2D floor plan overlay while it is open. When
// tapping on a marker, this function could be called that uses `floorPlanNavigateAndClose` to set the camera and close the
// 2D floor plan overlay.
const goto = (camera) => {
  if (floorPlanNavigateAndClose !== null) {
    floorPlanNavigateAndClose(camera.x, camera.y, camera.z, 0.1, 0.1);
    floorPlanNavigateAndClose = null;
  }
};

fieldOfViewChanged

Fires when the camera field of view has been changed. Returns a number in degrees.

globalBoundingBoxInitialized

Fires when the global bounding box of the model has been determined.

Data Properties

hideUpdated

Fires when the object hidden set has been updated.

hideSimilarCompleted

Fires when the Hide Similar from the right click context menu operation has completed.

intersectPointClick

Fires when a mouse click occurs on any part of the model and returns that point of intersection.

Data Properties

isolateCompleted

Fires when the Isolate from the right click context menu operation has completed.

messages

Fires when the webviewer throws a warning or error.

Data Properties

measured

Fires when measuring two objects has completed.

modelTreeParentInteracted

Fires when an object in the Model Objects has been interacted with.

Data Properties

markupDisplayed

Fires when markup from a viewpoint has been displayed.

markupDismissed

Fires when markup from a viewpoint has been dismissed.

navigationChanged

Fires when the navigation mode has changed.

Data Properties

objectDoubleClick

Fires on double mouse clicks. If the double mouse click occurs on an object, this event returns a Meshnode Index, otherwise -1 is returned. A double click also produces one objectSingleClick event.

objectSingleClick

Fires on a single mouse click.

Data Properties

objectHide

Fires when objects have been hidden.

Data Properties

objectUnhide

Fires when objects have been removed from the hidden set.

Data Properties

objectSelect

Fires when an object has been selected. Does not fire if empty space is clicked because nothing has been selected.

Data Properties

objectDeselect

Fires when an object has been deselected. This event returns an array of object ids that were deselected.

optionsChanged

Fires when the Webviewer options have changed. This event fires when setOptions is called, or when actions cause the multiple selection option to change, such as keyboard shortcuts to multi select objects.

objectMeasure

Fires when objects are selected for measurement. This event returns a Meshnode Index of the object selected for measurement.

projectSettingsUpdated

Fires when the project settings have been updated.

Data Properties

projectSettingsLoaded

Fires when the project settings have been loaded.

Data Properties

renderReady

Fires when the webviewer is ready to render the model.

Data Properties

redo

Fires when the keyboard shortcut to redo is pressed. This event fires regardless if there is anything to redo.

selectTool

Fires when a tool has been activated.

Data Properties

selectedUpdated

Fires when the selection set of objects has been updated. This event returns an array of the full set of selected object ids at the time of selection update.

singleClick

Fires when a single click occurs in the webviewer container element. This event returns a MouseEvent object.

sectionBoxDisplayConfigured

Fires when the section box display is configured (e.g. via model.configureSectionBoxDisplay).

Data Properties

sectionBoxDisplayToggled

Fires when the section box display is toggled on or off (e.g. via model.toggleSectionBoxDisplay).

Data Properties

sectionBoxSet

Fires when a section box has been applied.

sectionPlaneAdded

Fires when section planes have been applied.

sectionPlaneRemoved

Fires when a section plane has been removed.

sectionsCleared

Fires when all section planes have been removed as a result of individually removing all the planes, calling clearSection, or calling removeSectionBox.

savedViewpointClicked

Fires when a Saved Viewpoint from the Viewpoints tool has been clicked on.

undo

Fires when the keyboard shortcut to undo is pressed. This event fires regardless if there is anything to undo.

windowComponentChanged

Fires when a window based tool has changed its position or size.

Data Properties

windowOpen

Fires when a window based tool has been opened.

Data Properties

windowClose

Fires when a window based tool has been hidden.

Data Properties

objectTreeUpdated

Fires when a filter has been applied to the Object Tree or if the filtered has been cleared. When the filter is cleared, this event returns a null payload.

Data Properties

Model Namespace

Get Meshnode from Meshnode Index

getMeshnode(meshnodeIndex);

Description

Retrieves a JavaScript object that describes the object.

Parameters

Returns

Promise<Meshnode | null> 

See Meshnode.

Namespace

Model

Get Meshnode from Object ID

getMeshnodeFromObjectId(objectId);

Description

Retrieves the Meshnode associated with an objectId or null if there is none.

objectId’s are returned by these Rest endpoints:

• BIM Property File Objects: https://developers.procore.com/reference/rest/v1/bim-model-objects?version=1.0
• BIM Model Objects: https://developers.procore.com/reference/rest/v1/bim-model-objects?version=1.0

Parameters

Returns

Promise<Meshnode>

See Meshnode.

Namespace

Model

Get Hidden Meshnode Indices

getHiddenMeshnodeIndices();

Description

Retrieves a list of meshnode indices that are currently hidden.

Parameters

None

Returns

Promise<number[]>

Namespace

Model

Add Hidden Meshnode Indices

addHiddenMeshnodeIndices(meshnodeIndices);

Description

Hides meshnode indices. Does not clear previous hiding(s).

Parameters

Returns

Promise<void>

Namespace

Model

Has Hidden Meshnode Indices

hasHiddenMeshnodeIndices(meshnodeIndices);

Description

Checks if passed meshnode indices are hidden. Returns true is all the meshnode indices in the array are hidden. Otherwise false is returned if at least one meshnode is not hidden.

Parameters

Returns

Promise<boolean>

Namespace

Model

Clear Hidden Meshnode Indices

clearHiddenMeshnodeIndices();

Description

Clear hidden meshnode indices.

Parameters

None

Returns

Promise<boolean>

Namespace

Model

Get Selected Meshnode Indices

getSelectedMeshnodeIndices();

Description

Retrieves a list of meshnode indices that are currently selected.

Parameters

None

Returns

Promise<number[]>

Namespace

Model

Add Selected Meshnode Indices

addSelectedMeshnodeIndices(meshnodeIndices);

Description

Selects meshnode indices. Does not clear previous selection(s).

Parameters

Returns

Promise<boolean>

Namespace

Model

Has Selected Meshnode Indices

hasSelectedMeshnodeIndices(meshnodeIndices);

Description

Checks if passed meshnode indices are selected. Returns true is all the meshnode indices in the array are selected. Otherwise false is returned if at least one meshnode index is not selected.

Parameters

Returns

Promise<boolean>

Namespace

Model

Clear Selected Meshnode Indices

clearSelectedMeshnodeIndices();

Description

Deselects all meshnodes.

Parameters

None

Returns

Promise<boolean>

Namespace

Model

Set Meshnode Color

setMeshnodeColor(meshnodeIndex, hexColor, opacity);

Description

Overrides the color of a meshnode.

Parameters

Returns

undefined

Namespace

Model

Set Object Color

setObjectColor(colorDescriptor);

Description

Changes the color of an object while in three modes; default, selected or xray. Default is while the object is neither selected or in X Ray mode. Selected is while the object is selected. X Ray is while in X Ray mode.

Parameters

ColorDescriptor

A ColorDescriptor is composed of a palette, which may contain at least one of default, xray, or selected, and an array of object ids to apply it to.

{
  palette: {
    default: {color: '#ff0000', opacity: 1},
    xray: {color: '#00ff00', opacity: 1},
    selected: {color: '#0000ff', opacity: 1}
  },
  objectIds: [1, 2, 3]
}

Returns

undefined

Namespace

Model

Clear Object Color

clearObjectColor(objectIds);

Description

Clears object colors set by setObjectColor defined by sets of object ids.

Parameters

Returns

undefined

Namespace

Model

Clear All Object Color

clearAllObjectColor();

Description

Clears all object colors set by setObjectColor.

Parameters

None

Returns

undefined

Namespace

Model

Get Sections

getSections(format);

Description

Returns the current sectioning information as set by the Section Box tool or the sectioning API methods (e.g. setSectionBox and addSectionPlane).

Parameters

Returns

The format parameter determines the shape of this data.

The bcf format will return an array of BCF clipping plane. If no section is set it will return [].

The autodesk format will return an Autodesk Section Data object. If no section is set it will return null.

Promise<SectionDataProcoreFormat | SectionDataAutodeskFormat | null>

Namespace

Model

Set Section Box

setSectionBox(minXYZ, maxXYZ, rotation, showCoachmark);

Description

Sets section box given an XYZ max and min and rotation(optional);

Parameters

Returns

Promise<void>

Namespace

Model

Remove Section Box

removeSectionBox();

Description

Removes section box.

Parameters

None

Returns

Promise<void>

Namespace

Model

Reset Section Box

resetSectionBox();

Description

Resets section box to global bounding box of model.

Parameters

None

Returns

Promise<void>

Namespace

Model

Toggle Section Box Display

toggleSectionBoxDisplay(enable, options);

Description

Sets the on/off status of the section box display.

The section box display is the UI widget that allows users to interactively set the section box.

When turned on it will take the size of the first that is defined:

• the size of the last set section box in this session (e.g. via a viewpoint or SDK methods such as model.setSectionBox)
• the size of the last set section box display in this session (i.e. if the user has enabled the section box display at least once)
• the global bounding box of the model

When turned off it will clear all sections.

If the section box is set while the display is toggled on, the display will also change size to match the section box.

Overriding Section Box Setup

If you’d like to use your own logic for applying/removing the actual section box, you can configure model.toggleSectionBoxDisplay to use the size of the currently applied section box with the overrideSectionBoxSetup option.

This can also be configured for all calls with model.configureSectionBoxDisplay.

When overrideSectionBoxSetup is true, you must set a section box manually before calling model.toggleSectionBoxDisplay.

// Starting with no section applied
model.clearSection();

// BAD - throws error because no applied section box to take size of
model.toggleSectionBoxDisplay(true, { overrideSectionBoxSetup: true });

// GOOD - section box display takes size of applied section box
model.setSectionBox({ x: 0, y: 0, z: 0 }, { x: 1, y: 1, z: 1 }, { x: 0, y: 0, z: 0 }, false);
model.toggleSectionBoxDisplay(true, { overrideSectionBoxSetup: true });

// GOOD - using global config
model.configureSectionBoxDisplay({ overrideSectionBoxSetup: true });
model.setSectionBox({ x: 0, y: 0, z: 0 }, { x: 1, y: 1, z: 1 }, { x: 0, y: 0, z: 0 }, false);
model.toggleSectionBoxDisplay(true);

Parameters

ToggleSectionBoxDisplayOptions

Returns

undefined

Namespace

Model

Configure Section Box Display

configureSectionBoxDisplay(config);

Description

Configures how the section box display (controlled by model.toggleSectionBoxDisplay) will appear.

When the section box display is enabled, calling configureSectionBoxDisplay will take effect immediately. When the section box display is not enabled, the configuration changes will apply the next time the section box display is enabled.

Parameters

ConfigureSectionBoxDisplayConfig

Returns

undefined

Namespace

Model

Get Section Box Display

getSectionBoxDisplay();

Description

Gets the current section box display status.

Parameters

None

Returns

{
  enabled: boolean,
  configuration: ConfigureSectionBoxDisplayConfig,
  bbox: {
    min: { x: number, y: number, z: number },
    max: { x: number, y: number, z: number },
  },
}

For ConfigureSectionBoxDisplayConfig schema, see model.configureSectionBoxDisplay.

Namespace

Model

Add Section Plane

addSectionPlane(distance, normal);

Description

Adds a single section plane.

Parameters

Returns

undefined

Namespace

Model

Remove Section Plane

removeSectionPlane(uuid);

Description

Removes a single section plane.

Parameters

Returns

undefined

Namespace

Model

Clear Sections

clearSection();

Description

Removes all sections, planes and boxes.

Parameters

None

Returns

Promise<void>

Namespace

Model

Set Webviewer Configuration options

setOptions(options);

Description

Sets Webviewer configuration options. See Options. Currently can only set selection.

Parameters

Returns

undefined

Namespace

Model

Get relative planmap space position based on model space position

MapToModelSpace(
  point,
  modelA,
  modelB,
  planA,
  planB,
  imgSize,
  rect,
  direction,
  applyOffset
);

Description

Retrieve the model space point {x, y} relative to the planmap space point Note: applyOffset affected only when event renderReady has been fired.

Parameters

Returns

Promise<{
  x?: number;
  y?: number;
  dir_x?: number;
  dir_y?: number;
}>

Namespace

Model

Get relative model space position based on planmap space position

ModelToMapSpace(
  point,
  modelA,
  modelB,
  planA,
  planB,
  imgSize,
  rect,
  direction,
  applyOffset
);

Description

Retrieve the planmap space point {x, y} relative to the model space point Note: applyOffset affected only when event renderReady has been fired.

Parameters

Returns

Promise<{
  x?: number;
  y?: number;
  dir_x?: number;
  dir_y?: number;
}>

Namespace

Model

Get Global Offset

getGlobalOffset();

Description

Retrieves the global offset, if there is one.

Parameters

None

Returns

{offsetX: Number, offsetY: Number, offsetZ: Number}

Namespace

Model

Get Object

getObject(id, objectTreeName);

Description

Returns a model object with the given id. Contains data such as bounding box, hidden/selected states, and parent/child relationships.

Parameters

Returns

Promise<{
    id: number, 
    bbox: {
      min: number[],
      max: number[]
    }, 
    nodeType: number,
    hidden: boolean,
    selected: boolean,
    partiallySelected: boolean,
    parentId: number,
    children: number[]
}>

Namespace

Model

Get Objects

getObjects(objectIds, objectTreeName);

Description

Returns an array of model objects as defined by each id in the array. Contains data such as bounding box, hidden/selected states, and parent/child relationships.

If an id is not found, it will not be included in the returned array.

Parameters

Returns

Promise<[
  {
    id: number, 
    bbox: {
      min: number[],
      max: number[]
    }, 
    nodeType: number,
    hidden: boolean,
    selected: boolean,
    partiallySelected: boolean,
    parentId: number,
    children: number[]
  }
]>

Namespace

Model

Get Root Object

getRootObject(objectTreeName);

Description

Returns a model object which is the root of the model object tree. Contains data such as bounding box, hidden/selected states, and parent/child relationships.

Parameters

Returns

Promise<
{
    id: number, 
    bbox: {
      min: number[],
      max: number[]
    }, 
    nodeType: number,
    hidden: boolean,
    selected: boolean,
    partiallySelected: boolean,
    parentId: number,
    children: number[]
  } 
  | undefined>

Namespace

Model

Hide Objects

hideObjects(objectIds, objectTreeName);

Description

Hides objects defined by the array of object ids.

Parameters

Returns

Promise<boolean>

Namespace

Model

Hide All Objects

hideAllObjects(objectTreeName);

Description

Hides all objects.

Parameters

Returns

Promise<boolean>

Namespace

Model

Unhide All Objects

unhideAllObjects();

Description

Unhides all objects.

Parameters

None

Returns

Promise<boolean>

Namespace

Model

Unhide Objects

unhideObjects(objectIds, objectTreeName);

Description

Unhides objects defined by the array of object ids.

Parameters

Returns

Promise<boolean>

Namespace

Model

Get Hidden Objects

getHiddenObjects();

Description

Returns an array of object ids that are hidden.

Parameters

None

Returns

Promise<number[]>

Namespace

Model

Get Number Of Objects Hidden

getNumObjectsHidden();

Description

Retrieve the number of objects selected based on the FirstObject counting method.

Parameters

None

Returns

Promise<{ 
  count: number 
}>

Namespace

Model

Select Objects

selectObjects(objectIds, objectTreeName);

Description

Selects objects defined by the array of object ids.

Parameters

Returns

Promise<boolean>

Namespace

Model

Select All Objects

selectAllObjects(objectTreeName);

Description

Selects all objects.

Parameters

Returns

Promise<boolean>

Namespace

Model

Deselect All Objects

deselectAllObjects();

Description

Deselects all objects.

Parameters

None

Returns

Promise<boolean>

Namespace

Model

Deselect Objects

deselectObjects(objectIds, objectTreeName);

Description

Deselect objects defined by the array of object ids.

Parameters

Returns

Promise<boolean>

Namespace

Model

Get Selected Objects

getSelectedObjects();

Description

Returns an array of object ids that are selected.

Parameters

None

Returns

Promise<number[]>

Namespace

Model

Get Number Of Objects Selected

getNumObjectsSelected(method);

Description

Retrieve the number of objects selected based on the count method.

Parameters

Returns

Promise<{ 
  count: number 
}>

Namespace

Model

Set X Ray Mode

setXRayMode();

Description

Sets the rendering mode to X Ray. In this mode, all non selected geometry is rendered with a single color and are transparent.

Parameters

None

Returns

void

Namespace

Model

Set Normal Mode

setNormalMode();

Description

Sets the rendering mode to normal. In this mode, geometry is rendered using the geometries color and opacity values.

Parameters

None

Returns

void

Namespace

Model

Set Navigation Mode

setNavigationMode(mode);

Description

Sets the navigation mode. The navigation mode determines how the camera responds to mouse, keyboard, and wheel events.

Parameters

Returns

void

Namespace

Model

Set Measurement

setMeasurement(enable);

Description

Enables or disables the measurement tool. Requires the Measurement Tool be enabled upon viewer initialization by adding MEASUREMENT_SD to the options tools array.

Parameters

Returns

void

Namespace

Model

Filter Object Tree

filterObjectTree(objectIds);

Description

Constructs a filtered object tree from an array of object id’s. The filtered object tree is used to determine which objects are visible in the Model Objects tool. Additionally, when the filtered object tree is enabled, methods that get, select, or hide nodes can operate on this filtered object tree instead of the full object tree.

When a filtered object tree is enabled, the full object tree is kept in synch with changes made on the filtered tree and vice versa. For example, if you select an object in the filtered tree, the full tree will also have that object selected. This is to ensure that the rendering is kept in synch with the Model Objects tool.

Consider the following example:

// For illustrative purposes, the full tree looks like this
// 0
// ├── 1
// │   ├── 2
// │   └── 3
// └── 4
//     ├── 5 // <-- This object is named `Wall`
//     └── 6

const response = await this.viewer.api.filterObjects({
  filterField: 'name',
  filterValue: 'wall',
});
const objects = await response.json();
const objectIds = objects.map((object) => object.id);
await this.viewer.model.filterObjectTree(objectIds);

// After a filter has been applied, a filtered tree might look like this
// 0
// └── 4
//     └── 5

// Both full and filtered trees are available for you to take actions on.
// For example, you can select a node in the filtered tree.
// This will select the node in the full tree as well and display the object as being selected
// in the Model Objects Tool and in the rendering.
await this.viewer.model.selectObjects([5], 'filtered');

// Any method that would take an optional parameter of `objectTreeName` will default to the full tree.
// Returns:
// {
//    id: 0,
//    children: [1, 4],
//    ...
// }
await this.viewer.model.getRootObject(); 

// You can specify the filtered tree by passing in the name of the filtered tree, in this case 'filtered'
// Returns:
// {
//    id: 0,
//    children: [4],
//    ...
// }
await this.viewer.model.getRootObject('filtered'); 

The following methods now accept an optional parameter objectTreeName. If not supplied, the default object tree is used. This is the same as passing in default for the objectTreeName parameter. If a filtered object tree is enabled, the objectTreeName parameter can be set to filtered to invoke the method on the filtered object tree instead of the default object tree.

• getObjects
• getObject
• getRootObject
• hideObjects
• hideAllObjects
• unhideObjects
• selectObjects
• selectAllObjects
• deselectObjects

Parameters

Returns

Promise<void>

Namespace

Model

Clear Object Tree Filter

clearObjectTreeFilter();

Description

Clears the filtered object tree. This will cause the Model Objects tool to display all objects in the model.

Parameters

None

Returns

Promise<void>

Namespace

Model

Get Viewpoint

getViewpoint();

Description

Gets the current state of the model as a Viewpoint, which can be used to create a BIM Viewpoint

Includes the following:

• applied sectioning
• camera type and orientation

Will currently always return empty redlines as the Web Viewer does not yet have a way to author them.

Parameters

None

Returns

Promise<Viewpoint>

Namespace

Model

Set Viewpoint

setViewpoint(viewpoint);

Description

Sets the current state of the model to match the Viewpoint, which can be gotten from endpoints that return a BIM Viewpoint

Includes the following:

• applied sectioning
• camera type and orientation
• redlines

Parameters

Returns

Promise<void>

Namespace

Model

Markup Namespace

Clear

clear();

Description

Clears all drawn markup, e.g. from a markup.draw call.

Parameters

None

Returns

void

Namespace

Markup

Draw

draw(markupData);

Description

Draws various types of markup (ellipses, lines, arrows, texts, and rects) on an SVG canvas based on the provided markupData

The markupData is an object that contains arrays of different types of markup elements, each with their own properties.

Any existing markup will NOT be cleared. Subsequent draw calls will be drawn on top of previous ones. Use markup.clear to clear the screen before subsequent markup.draw calls if necessary.

Parameters

MarkupData

The markupData object contains arrays of different types of markup elements.

Each type of markup element has its own properties:

Shared Properties

These properties are shared by all shapes.

Box Ellipses

Radius Ellipses

Lines and Arrows

Texts

Rects

Example Usage

markup.draw({
  ellipses: [
    // Unfilled box ellipse
    {
      stroke: 'rgba(255, 0, 0, 0.5)',
      min: { x: 257.47786244734874, y: 220 },
      max: { x: 320, y: 302.52213755265126 },
      strokeWidth: 3,
    },
    // Filled box ellipse
    {
      stroke: 'rgba(255, 0, 255, 1)',
      fill: 'rgba(0, 255, 255, 0.5)',
      min: { x: 257.47786244734874, y: 300 },
      max: { x: 320, y: 362.52213755265126 },
      strokeWidth: 3,
    },
    // Filled radius ellipse
    {
      stroke: 'chartreuse',
      fill: 'dodgerblue',
      radius: { x: 50, y: 50 },
      center: { x: 50, y: 50 },
      strokeWidth: 5,
    },
  ],
  lines: [
    {
      stroke: 'rgba(0, 255, 0, 0.5)',
      start: { x: 320, y: 240 },
      end: { x: 632.6106877632562, y: 302.52213755265126 },
      strokeWidth: 3,
    },
  ],
  arrows: [
    {
      stroke: 'rgba(0, 0, 255, 0.5)',
      start: { x: 320, y: 240 },
      end: { x: 632.6106877632562, y: 177.47786244734877 },
      strokeWidth: 3,
    },
  ],
  texts: [
    {
      text: 'text',
      origin: { x: 632.6106877632562, y: 240 },
      fill: 'rgba(255, 255, 0, 0.5)',
      font: '9px verdana',
    },
  ],
  rects: [
    {
      x: 250,
      y: 300,
      width: 50,
      height: 100,
      radius: { x: 10, y: 10 },
      fill: 'rgba(255, 0, 0, 0.5)',
      stroke: 'rgba(0, 255, 0, 0.5)',
    },
  ],
})

Returns

void

Namespace

Markup

Draw Anchored

drawAnchored(anchoredMarkupData);

Description

Draws various types of markup (ellipses, lines, arrows, texts, and rects) on an SVG canvas based on the provided anchoredMarkupData

The anchoredMarkupData is an object that contains arrays of different types of markup elements, each with their own properties.

Once anchoredMarkupData is drawn via a call to drawAnchored, the markup will be redrawn whenever the cameraUpdated event is fired. The anchored markup will continue drawing at its anchored position in the model until markup.clear is called. Unless you are updating the anchor positions, there is no reason to call drawAnchored multiple times.

Parameters

AnchoredMarkupData

The anchoredMarkupData object contains arrays of different types of markup elements.

Shared Properties

Anchored shapes share most properties with their unanchored counterparts used in markup.draw, but replace properties that position the shape in px coordinates with anchor or anchorStart/anchorEnd.

Anchored Box Ellipses

Anchored Radius Ellipses

Anchored Lines and Anchored Arrows

Anchored Texts

Anchored Rects

Example Usage

markup.drawAnchored({
  ellipses: [
    // Unfilled box ellipse with an anchor offset
    {
      stroke: 'rgba(255, 0, 0, 0.5)',
      min: { x: 0, y: 0 },
      max: { x: 50, y: 50 },
      anchor: { x: 91, y: 8, z: 1 },
      strokeWidth: 3,
    },
    // Filled box ellipse with an anchor offset
    {
      stroke: 'rgba(255, 0, 255, 1)',
      fill: 'rgba(0, 255, 255, 0.5)',
      min: { x: 0, y: 0 },
      max: { x: 50, y: 50 },
      anchor: { x: 91, y: 8, z: 1.5 },
      strokeWidth: 3,
    },
    // Filled radius ellipse
    {
      stroke: 'chartreuse',
      fill: 'dodgerblue',
      radius: { x: 25, y: 25 },
      anchor: { x: 91, y: 8, z: 2 },
      strokeWidth: 5,
    },
    // zIndex'd ellipse on bottom
    {
      stroke: 'yellow',
      fill: 'red',
      radius: { x: 25, y: 25 },
      anchor: { x: 91, y: 8, z: 3.5 },
      anchorOffset: { x: -10, y: -10 },
      strokeWidth: 5,
      zIndex: 1,
    },
    // zIndex'd ellipse on top
    {
      stroke: 'magenta',
      fill: 'blue',
      radius: { x: 25, y: 25 },
      anchor: { x: 91, y: 8, z: 3.5 },
      anchorOffset: { x: 10, y: 10 },
      strokeWidth: 5,
      zIndex: 3,
    },
  ],
  lines: [
    {
      stroke: 'rgba(0, 255, 0, 0.5)',
      anchorStart: { x: 90.5, y: 7.5, z: 2 },
      anchorEnd: { x: 91.5, y: 8.5, z: 2 },
      strokeWidth: 3,
    },
  ],
  arrows: [
    {
      stroke: 'rgba(0, 0, 255, 0.5)',
      anchorStart: { x: 90.5, y: 8.5, z: 2 },
      anchorEnd: { x: 91.5, y: 7.5, z: 2 },
      strokeWidth: 3,
    },
  ],
  texts: [
    {
      text: 'text',
      anchor: { x: 91, y: 8, z: 2.5 },
      anchorOffset: { x: 10, y: 10 },
      fill: 'rgba(255, 255, 0, 0.5)',
      font: '9px verdana',
    },
  ],
  rects: [
    {
      anchor: { x: 91, y: 8, z: 3 },
      width: 40,
      height: 25,
      radius: { x: 10, y: 10 },
      fill: 'rgba(255, 0, 0, 0.5)',
      stroke: 'rgba(0, 255, 0, 0.5)',
    },
    // zIndex'd rect in middle
    {
      anchor: { x: 91, y: 8, z: 3.5 },
      width: 40,
      height: 25,
      radius: { x: 10, y: 10 },
      fill: 'green',
      stroke: 'cyan',
      strokeWidth: 5,
      zIndex: 2,
    },
  ],
})

Returns

Promise<void>

Namespace

Markup

Set Redlines

setRedlines(redlinesData, fov);

Description

Draws various types of markup (ellipses, lines, arrows, and texts) on an SVG canvas based on the provided redlinesData and fov (field of view). This method is similar to markup.draw, but is more specific to drawing red line markup from Navisworks.

The redlinesData is an object that contains arrays of different types of markup elements, each with their own properties.

The fov is used to calculate the range of the x and y axes. The tangent of fov is used as a range for positive Y values. This is compared to the aspect ratio of the viewport to get a range for positive X values.

Example:

• fov is 45deg, tangent of 45 is 1, so positive Y will range from 0 to 1.
• Viewport aspect ratio (determined from canvas width and height) is 2, so positive X will range from 0 to 2.
• For a markup line that starts at (0.5, 1), the line will start exactly in the middle of the first quadrant (upper right).

When called, any existing markup will first be cleared before the markup data is drawn.

After markup drawing is complete, the markupDisplayed event will be published.

Parameters

RedlinesData Object

The redlinesData object contains arrays of different types of markup elements.

Each type of markup element has its own properties:

Ellipses

Lines

Arrows

Texts

Returns

void

Namespace

Markup

Cache Namespace

Is the model cached

hasModel(urlsObject);

Description

Checks if the internal caching system contains model data for an array of urls.

Parameters

Example

ProcoreBim.Cache.hasModel({
  meshUrl: 'samples/vortex.mesh',
  meshnodeUrl: 'samples/vortex.meshnode',
  nodeUrl: 'samples/vortex.node',
}).then(function (isCached) {
  console.log(isCached);
});

Returns

Promise(boolean)

Remove Model

removeModel(urlsObject);

Description

Remove model data for an array of urls.

Parameters

Example

ProcoreBim.Cache.removeModel({
  meshUrl: 'samples/vortex.mesh',
  meshnodeUrl: 'samples/vortex.meshnode',
  nodeUrl: 'samples/vortex.node',
}).then(function (modelRemoved) {
  console.log(modelRemoved);
});

Returns

Promise(boolean)

GUI Namespace

Add Context Menu Item

addContextMenuItem({label, id, shortcut, onClick, singleObject});

Description

Retrieves a JavaScript object that describes the object.

Parameters

Returns

HTMLDivElement

Namespace

GUI

Remove Context Menu Items

removeContextMenuItems({contextMenuItemIds});

Description

Retrieves a JavaScript object that describes the object.

Parameters

Returns

void

Namespace

GUI

Set Toolbar Hidden

setToolbarHidden(hidden);

Description

Allows you to set the visibility of the bottom toolbar.

Parameters

Returns

void

Namespace

GUI

Set Hotkeys Enabled

setHotkeysEnabled(enabled);

Description

Allows you to enable or disable hotkeys. For example, pressing “X” will turn on the X-Ray mode when hotkeys are enabled. When disabled, the hotkeys will not work and pressing “X” will have no effect.

Parameters

Returns

void

Namespace

GUI

Options

Required Options

parentElement

DOMElement

DOM node to attach viewer to.

{
  parentElement: document.getElementById('myViewer');
}

projectId

number

The id of the project the model has been published to.

{
  projectId: 25000;
}

companyId

number

The id of the company the model has been published to.

{
  companyId: 10;
}

Required Options for Model Revision

If you are planning to use the Web Viewer SDK to view a model revision, you will need to provide the following options. These are models published to the Models Tool.

modelId

number

ID of the associated BIM Model

{
  modelId: 999;
}

modelRevisionId

number

ID of the associated BIM Model Revision

{
  modelRevisionId: 888;
}

meshUrl

string

URL to mesh binary provided by a Procore service.

{
  meshUrl: 'https://foo.com/geometry/mesh';
}

meshnodeUrl

string

URL to mesh binary provided by a Procore service.

{
  meshnodeUrl: 'https://foo.com/geometry/meshnode';
}

nodeUrl

string

URL to mesh binary provided by a Procore service.

{
  nodeUrl: 'https://foo.com/geometry/node';
}

Required Options for File Extraction

If you are planning to use the Web Viewer SDK to view a model with a file extraction, you will need to provide the following options. For example, models uploaded to the Documents Tool can be viewed with a file extraction.

fileExtractionId

number

ID of the file extraction associated to the model.

{
  fileExtractionId: 23;
}

Optional Options

accessToken

string

OAuth access token used to authenticate requests to the Procore API made by the Web Viewer SDK on your behalf (e.g. fetching an object’s properties). Specifically it adds an Authorization header with the provided token to each request. See Making Your First API Call for details on retrieving an access token.

Note also that this setup implies an Implicit Grant flow in that your access token will be present on the browser rather than only present on a server, which may be a security concern. See OAuth 2.0 Implicit Grant for details on Implicit Grant flow.

If this is not provided as an option, you will need to intercept the SDK’s requests and attach the Authorization header yourself in order for them to succeed.

Additionally, the access token will eventually expire (in 24 hours currently for an implicitly granted token) and requests made by the SDK will fail. We don’t yet have a way to notify of these errors and refresh the in-use access token. One workaround is to keep track of the expiration time for the access token (provided in the expires_in query param in the Implicit Grant flow) and re-instantiate the ProcoreBim.Webviewer with the new access token.

{
  accessToken: '1234567890abdefghijkl',
}

baseUrl

string

The baseUrl is a mechanism for determining which version of the Procore API you will hit.

For example, while developing a third-party Procore App, you may want to utilize one of the Sandbox Environments. To use the Development Sandbox, you could pass baseUrl: 'https://sandbox.procore.com/' and any requests made by the SDK will be made to that origin.

Another example is if you want to avoid using the Implicit Grant flow you might set up a server at say https://auth-proxy.myapp.com and pass that in as the baseUrl. All SDK requests will then be made to your server which could add the Authorization header and make the actual request to the Procore API.

{
  baseUrl: 'https://api.procore.com',
}

bcfCamera

Object

Initializes the Webviewer with the camera.

{
  bcfCamera: {
    perspective_camera: {
      camera_view_point: {
        x:100,
        y:100,
        z:10
      },
      camera_direction: {
        x:0,
        y:1,
        z:0
      },
      camera_up_vector: {
        x:0,
        y:0,
        z:1
      },
      field_of_view: 1.3,
      target_distance: 1000000
    }
  }
}

min_boundary

Object

Defines the minimum boundary of the model. If max_boundary is also defined, both min_boundary and max_boundary are used to create a section box which will only render objects within that section box.

{
  min_boundary: {
      z:"-14.1686084710",
      y:"20.1924446284",
      x:"-26.6485348162"
  }
}

max_boundary

Object

Defines the maximum boundary of the model. If min_boundary is also defined, both max_boundary and min_boundary are used to create a section box which will only render objects within that section box.

{
  max_boundary: {
      z:"11.8769418043",
      y:"155.7780451539",
      x:"17.0583084307"
  }
}

rotation

Object

If min_boundary and max_boundary are defined, then you can also set the rotation of the section box.

{
  rotation: {
      z:"11.8769418043",
      y:"155.7780451539",
      x:"17.0583084307"
  }
}

multiselect

boolean

Sets the object selection mode.

{
  multiselect: false;
}

tools

Array

[
  ProcoreBim.Webviewer.tools.BOTTOMTOOL,
  ProcoreBim.Webviewer.tools.COACHMARKS,
  ProcoreBim.Webviewer.tools.MEASUREMENT_SD
];

Pre-built tools to be enabled.

This array can be composed of both constants and objects. You can use objects to set tool specific options. When an object is passed, the object MUST have the key, type and the value be the tool name. Other keys in this object are options you want to set.

For example:

[
  ProcoreBim.Webviewer.tools.BOTTOMTOOL,
  { type: ProcoreBim.Webviewer.tools.MEASUREMENT_SD, center_lock: true }
];

See Tools for further information.

Objects

Perspective Camera Object

{
  perspective_camera: {
    camera_view_point:  {x: Number, y: Number, z: Number},
    camera_direction:  {x: Number, y: Number, z: Number},
    camera_up_vector:  {x: Number, y: Number, z: Number},
    field_of_view: Number,
    target_distance: Number
  }
}

Orthogonal Camera Object

{
  orthogonal_camera: {
    camera_view_point: {x: Number, y: Number, z: Number},
    camera_direction: {x: Number, y: Number, z: Number},
    camera_up_vector: {x: Number, y: Number, z: Number},
    view_to_world_scale: Number,
    target_distance: Number,
    vertical_extent: Number
  }
}

Meshnode

{
  bbox: Float32Array(6),
  matrix: Float32Array(12),
  meshData: [
    {
      byteLength: Number,
      color: Number,
      faces: Uint16Array(n),
      offset: Number,
      opacity: Number,
      vertices: Float32Array(n)
    }
  ]
}