BIM / 3D Guide

This guide covers the NPM SDK 3D workflow. Mount the viewer, wait for viewer.ready(), and open a 3D document before enabling BIM controls. A non-3D active document can cause Canvas to reject a 3D command.

• 3D tools
• 3D API
• File opening

Keep the host interface disabled until the active document is known to be 3D. Register selection listeners before enabling part selection so that the first selected part is not missed.

• 1Mount the viewer, wait for readiness, and open the model.
• 2Subscribe to partSelected and selectionCleared.
• 3Enable part selection with selection events.
• 4Expose view and visual controls only while a 3D document is active.
• 5Apply one visual-state change at a time and wait for its result before presenting it as applied.
• 6Remove subscriptions and destroy the viewer on route cleanup.

Part selection is event-driven. Enable it with emitSelectionEvents: true, populate the details panel from partSelected, and clear that panel only when selectionCleared arrives. Do not infer a selected part from the select command itself.

• viewer.tools.threeD.on("partSelected", handlePartSelected)
• viewer.tools.threeD.on("selectionCleared", handleSelectionCleared)
• viewer.tools.threeD.setSelect({ enabled: true, emitSelectionEvents: true })
• viewer.tools.threeD.setSelect({ enabled: false })

Pass explicit enabled values for toggle-like modes so host state does not drift from Canvas. Use reset as the single recovery action for a model that has accumulated several visual changes.

• viewer.tools.threeD.setBirdEyeView()
• viewer.tools.threeD.setMarkupSelect({ enabled: true })
• viewer.tools.threeD.setMarkupSelect({ enabled: false })
• viewer.tools.threeD.setWalkthrough({ enabled: true })
• viewer.tools.threeD.setWalkthrough({ enabled: false })
• viewer.tools.threeD.setHidePartsMode({ enabled: true })
• viewer.tools.threeD.setHidePartsMode({ enabled: false })
• viewer.tools.threeD.resetModel()

Use the slider or form values as the requested state and update the confirmed UI only after the result succeeds. Canvas interprets supported explode-distance and cross-section coordinate ranges, so validate any product-specific limits in the host before sending them.

• viewer.tools.threeD.setExplode({ enabled: true, distance: 40 })
• viewer.tools.threeD.setExplode({ enabled: false, distance: 0 })
• viewer.tools.threeD.setTransparency({ enabled: true, valuePercent: 40 })
• viewer.tools.threeD.setTransparency({ enabled: false, valuePercent: 0 })
• viewer.tools.threeD.setCrossSection({ enabled: true, x: 0.25, y: 0, z: 0 })
• viewer.tools.threeD.setCrossSection({ enabled: false, x: 0, y: 0, z: 0 })

Keep the model visible while users inspect parts or adjust visual modes. The reference workflow uses an active-file rail, a compact 3D toolbar, and a persistent details panel; use the same task-oriented arrangement in an NPM host application, but send only documented NPM calls from those controls.

• Use a file rail or picker that identifies the active model and provides an explicit Open action.
• Keep all BIM controls disabled until the selected model is ready and confirmed as 3D.
• Separate Tools from Navigation controls so part selection, markup selection, hide-parts, explode, cross section, and transparency do not compete with walkthrough and reset.
• Use icon controls with accessible names and visible tooltips when labels are not permanently shown.
• Open a labelled range popover for explode distance, transparency percentage, and cross-section offset; show the current value, affected scope, and selected cross-section axis.
• Place selected-part details in a side panel that does not cover the model.
• Render only fields supplied by partSelected, such as the part name and available properties; do not fabricate unavailable IFC values.
• Keep Reset visible as the recovery action after a sequence of model adjustments.

Treat each 3D control as unavailable, ready, pending, confirmed, or failed. The host may optimistically show the requested slider value, but it must retain the last confirmed value until the corresponding NPM result succeeds.

• Disable all 3D controls until the active document is confirmed as 3D.
• Show the selected file as opening until the model is ready; do not enable the toolbar from file choice alone.
• Disable the initiating control while its command is pending and prevent duplicate range submissions.
• Use explicit enabled values when a UI button turns a mode on or off; do not rely on toggle behavior.
• When switching between product-defined exclusive modes, disable the previous mode before enabling the next one.
• Keep a range popover associated with its trigger using aria-expanded and a descriptive dialog label.
• Announce model status, selected-part changes, and command failures with an aria-live status region.
• Give every icon control an accessible name and every range input a visible label, current value, and unit or axis context.
• Clear the details panel only from selectionCleared; reset alone is not a selection-clear confirmation.

Every 3D command resolves with a result only after Canvas returns its matching event, and can reject when the viewer is not ready, the broker is unavailable, Canvas times out, or Canvas reports a failure. Preserve the last confirmed control state until a command succeeds.

• Disable the initiating control while its command is pending.
• If result.success is false, keep the prior confirmed state and show result.error.
• If the promise rejects, restore the control and offer retry after checking that a 3D document is active.
• Do not assume an omitted enabled value preserves the current mode; send an explicit value.
• Call the two selection unsubscribe functions during route cleanup.

Test against a supported 3D model and a non-3D document.

• BIM controls remain unavailable until a 3D document is open.
• Selecting a part updates the details panel from partSelected.
• Clearing selection empties the details panel from selectionCleared.
• Bird-eye, markup selection, walkthrough, hide-parts, explode, transparency, and cross-section controls retain their prior confirmed state after failure.
• Reset succeeds only after its documented result; selected-part UI changes only when the relevant selection event occurs.
• Route cleanup stops events before the viewer is destroyed.