js-sdk

NiraAPI.Viewer

The Viewer class provides an interface to a Nira iframe embed.

Key Features

Set active tool modes: Switch between modes like Orbit, Pan, Zoom, etc. Useful for implementing navigation tool buttons with custom styling.
Manage callouts: Activate callouts or change the view bookmark of a callout.
Events: React to events like asset loading/unloading, tool mode changes, and callout interactions.
Signed URLs: Embed an asset with a time-limited signed URL and keep it working with access_renewal_needed and renewAccess.
View state: Set view state attributes for the session, such as object visibilities or rendering parameters. Useful for implementing more complex "configurators" that are not achievable via the View Variants dropdown.
Control view options: Show or hide certain UI elements and control various behaviors of the viewer. Useful when implementing your own callout or navigation UI. See IViewOptions.

Plan and add-on required

The Viewer API requires a Growth or Enterprise plan and the purchase of the Viewer API add-on. An organization admin can buy it under Admin Options > Billing.

Samples

Navigation tool buttons with custom styling: Navigation buttons with custom styling. The button styling in this example is visually basic and is only for illustrative purposes.
Object visibility toggle with custom button styling: Please note, for simple use cases, this is more easily accomplished with no code using View Variants. The button styling in this example is visually basic and is only for illustrative purposes. For a more advanced use case of visibility changes, see the Advanced Configurator example below.
Advanced Configurator: A customer example of a more advanced configurator. When user makes a selection in the UI, the appropriate object visibility changes are made via setSessionState() and the appropriate camera movements are made via activateCallout(). It also uses basic event handling ('asset_load_finish' and 'asset_unload') to show/hide panel UI when the asset is loaded or unloaded.
Callout Handling: This is an example of how to implement your own callout creation and callout information display UX using the Viewer API. Please see the source code of the example for more details. This example is visually basic and is only for illustrative purposes.

Getting Started

1. Include viewer.js

Add the viewer.js script to your page:

<script src="https://sdk.nira.app/js/viewer.js"></script>

2. Add an Iframe

Include an iframe element on your page:

<iframe id="niraviewer" frameBorder="0" loading="lazy" class="niraIframe" src="YOUR_ASSET_URL"></iframe>

The src attribute should be set to a Nira asset URL. Also see Embedding a Nira asset with iframe.

3. Create a Viewer Instance

document.addEventListener("DOMContentLoaded", () => {
  const viewer = new NiraAPI.Viewer(document.getElementById("niraviewer"));
});

4. Call methods and handle events

// Engage the pan tool as soon as the asset loads
viewer.on("asset_load_finish", () => {
  viewer.setToolMode(NiraAPI.Toolmode.Pan);
});

viewer.on("toolmode", (toolmode) => {
  // Handle tool mode changes here. For example, activate a custom button in your UI.
});

Kind: static class of NiraAPI

Constructor

new NiraAPI.Viewer(elementOrId, options)

Creates a new NiraAPI.Viewer instance and attaches it to an iframe element. The second parameter is an optional object that controls certain behaviors of the Nira view (see IViewOptions).

Param	Type	Description
elementOrId	`string` \| `HTMLIFrameElement`	The iframe element or its ID.
options	`IViewOptions`	Optional configuration options.

Example

// Create a Viewer instance attached to an iframe with ID "nira-iframe"
const viewer = new NiraAPI.Viewer("nira-iframe");

Methods

viewer.on(name, callback)

Registers an event listener.

Kind: instance method of Viewer Category: Methods

Param	Type	Description
name	`string`	The name of the event to listen for.
callback	`function`	The callback function to execute when the event is emitted.

Example

// Listen for tool mode changes
viewer.on("toolmode", (toolmode) => {
  console.log("Tool mode changed to:", toolmode);
});

viewer.off(eventName, callback)

Unregisters an event listener.

Kind: instance method of Viewer Category: Methods

Param	Type	Description
eventName	`string`	The name of the event to stop listening for.
callback	`function`	The callback function to remove.

viewer.destroy()

Destroys the Viewer instance, cleaning up event listeners and intervals.

Kind: instance method of Viewer Category: Methods

viewer.setCameraState(cameraState)

Sets the current camera state for the loaded asset. See ICameraState for the available camera state parameters.

Kind: instance method of Viewer Category: Methods

Param	Type	Description
cameraState	`any`	Camera state parameters.

Example

// Set the current camera type to "Perspective" if it's not already:
viewer.setCameraState({ 'camType': "Perspective" });

viewer.setSessionState(state)

Sets the current view state for the loaded asset. See IViewState for the available view state parameters.

You can also explore available view state parameters within Nira:

Within Nira, click "Edit Mode"
Make one or more visual changes to your asset within Nira using the right panel
Click the "Save | Revert..." button
In the dialog that appears, expand the "Show Details" area. Any parameter change shown in this area can be passed via setSessionState().

Also see View Variants documentation for a no-code alternative that works in many cases.

Kind: instance method of Viewer Category: Methods

Param	Type	Description
state	`any`	View state parameters.

Example

// Disable the display of textures
viewer.setSessionState({ 'renderTextures': false });
// Hide the object named 'foliage'
viewer.setSessionState({ nodeVisibility: [{
  objectName: 'foliage'
}]});

viewer.getClippingVolume() ⇒ `Promise.<object>`

Gets the clipping volume parameters of the view state. See IClippingVolume.

The keys are the same as those accepted by setSessionState, so the result can be passed back to setSessionState or setClippingVolume to restore the same box. clippingScale, clippingRotate and clippingTranslate are null when the box has no valid value for them.

Call this once the asset has loaded, for example from an asset_load_finish handler. A request sent before the viewer is ready to receive it gets no answer and rejects with timeout.

The values are those of the last state the viewer received. A call made straight after setSessionState or setClippingVolume can return the values from before that change. To follow changes, listen for the clipping_volume_changed event instead.

Kind: instance method of Viewer Returns: Promise.<object> - Resolves with a NiraAPI.IClippingVolume object. Rejects with an Error whose message is the reason given by the viewer, or timeout when the viewer does not answer within 15 seconds.
Category: Methods
Example

// Read the current clipping volume:
const volume = await viewer.getClippingVolume();
console.log("Clipping enabled:", volume.clippingEnabled, "center:", volume.clippingTranslate);

Example

// Save the box when the user clicks Save, and put it back when they click Restore:
let savedVolume = null;
document.getElementById("save").addEventListener("click", async () => {
  savedVolume = await viewer.getClippingVolume();
});
document.getElementById("restore").addEventListener("click", () => {
  if (savedVolume) {
    viewer.setClippingVolume(savedVolume);
  }
});

viewer.setClippingVolume(volume)

Sets clipping volume parameters of the view state. See IClippingVolume.

This is the same as calling setSessionState with only the clipping volume keys. Any other key is dropped and named in a console.error message.

You can pass any subset of the keys. The ones you leave out keep their current values. This does not enable clipping by itself: include clippingEnabled: true to apply the volume. A key set to null, as getClippingVolume returns for a vector that has no value, is ignored.

Kind: instance method of Viewer Category: Methods

Param	Type	Description
volume	`Partial.<IClippingVolume>`	The clipping volume parameters to set.

Example

// Show only a 4 x 4 x 4 world unit cube centered on the origin:
viewer.setClippingVolume({
  clippingEnabled: true,
  clippingScale: { x: 2, y: 2, z: 2 },
  clippingRotate: { x: 0, y: 0, z: 0 },
  clippingTranslate: { x: 0, y: 0, z: 0 },
});

Example

// Move the center of the box to 3 units above the origin, keeping its size, rotation and enabled state:
viewer.setClippingVolume({ clippingTranslate: { x: 0, y: 3, z: 0 } });

viewer.renewAccess(url) ⇒ `Promise.<object>`

Asks the viewer to switch to a new signed URL for the asset it is already showing, so that access continues past the expiry of the current URL. The camera and session are kept.

The new URL must be for the same asset and the same level as the current URL, and must be on the same host. Otherwise the promise rejects with forbidden and the current URL stays valid until it expires.

Call this from an access_renewal_needed handler after you obtain a new signed URL from your own backend.

Kind: instance method of Viewer Returns: Promise.<object> - Resolves with an object whose exp is the expiry time of the new URL, in seconds since the epoch. Rejects with an Error whose message is the reason, which is one of expired, invalid, forbidden or rate_limited, or timeout when the viewer does not answer within 15 seconds.
Category: Methods

Param	Type	Description
url	`string`	The new signed URL.

Example

viewer.on("access_renewal_needed", async () => {
  const newUrl = await fetch("/my-backend/new-nira-url").then((r) => r.text());
  try {
    const { exp } = await viewer.renewAccess(newUrl);
    console.log("Access renewed until", new Date(exp * 1000));
  } catch (err) {
    console.error("Renewal failed:", err.message);
  }
});

viewer.setToolMode(toolmode)

Sets the current tool mode. Also see:

Kind: instance method of Viewer Category: Methods

Param	Type	Description
toolmode	`Toolmode`	The tool mode to set. Must be a value from the Toolmode enum

Example

// Set the tool mode to "Orbit"
viewer.setToolMode(NiraAPI.Toolmode.Orbit);

viewer.setCalloutViewBookmark(callout, [options])

Sets the view bookmark for the specified callout. Equivalent to clicking the Set bookmark menu item for the specified callout.

Kind: instance method of Viewer Category: Methods

Param	Type	Description
callout	`string`	The label or uuid of the callout to set as a view bookmark, or your externalId when `options.matchField` is `"externalId"`.
[options]	`Object`	Options for controlling how `callout` is interpreted.
[options.matchField]	`"uuid"` \| `"externalId"`	Which field `callout` refers to: `uuid` by default, or `externalId` to identify it by your own id.

Example

// Sets the view bookmark for callout with the label 'A1'.
viewer.setCalloutViewBookmark("A1");

Example

// Sets the view bookmark for the callout with the externalId 'inspection-2026-0042'.
viewer.setCalloutViewBookmark("inspection-2026-0042", { matchField: "externalId" });

viewer.activateCallout(callout, options)

Activates a callout with the specified label or uuid. Equivalent to clicking the Go to bookmark menu item for the specified callout.

Kind: instance method of Viewer Category: Methods

Param	Type	Description
callout	`string`	The label, uuid, title or defectTitle of the callout to activate, or your externalId when `options.matchField` is `"externalId"`.
options	`IActivateCalloutOptions`	Options for controlling the behavior of the callout activation, such as what happens to the camera view. See IActivateCalloutOptions.

Example

// Activate a callout by its UUID
viewer.activateCallout("A1");

Example

// Activate the callout with the externalId 'inspection-2026-0042'
viewer.activateCallout("inspection-2026-0042", { matchField: "externalId" });

viewer.deleteCallout(callout, [options])

Deletes a callout with the specified uuid.

Kind: instance method of Viewer Category: Methods

Param	Type	Description
callout	`string`	The uuid of the callout to delete, or your externalId when `options.matchField` is `"externalId"`.
[options]	`Object`	Options for controlling how `callout` is interpreted.
[options.matchField]	`"uuid"` \| `"externalId"`	Which field `callout` refers to: `uuid` by default, or `externalId` to identify it by your own id.

Example

// Deletes a callout by its UUID
viewer.deleteCallout("2997a059-f937-40c7-b4f3-42431f2b4f2b");

Example

// Deletes the callout with the externalId 'inspection-2026-0042'
viewer.deleteCallout("inspection-2026-0042", { matchField: "externalId" });

viewer.updateCallout(callout, data, [options])

Updates a callout with the specified uuid.

Kind: instance method of Viewer Category: Methods

Param	Type	Description
callout	`string`	The uuid of the callout to update, or your externalId when `options.matchField` is `"externalId"`.
data	`Partial.<ICalloutData>`	The data to update on the callout. Includes `externalId`, your own identifier for the callout.
[options]	`Object`	Options for controlling how `callout` is interpreted.
[options.matchField]	`"uuid"` \| `"externalId"`	Which field `callout` refers to: `uuid` by default, or `externalId` to identify it by your own id.

Example

// Updates a callout by its UUID
viewer.updateCallout("2997a059-f937-40c7-b4f3-42431f2b4f2b", { title: "A tree"});

Example

// Updates the callout with the externalId 'inspection-2026-0042'
viewer.updateCallout("inspection-2026-0042", { title: "Renamed" }, { matchField: "externalId" });

viewer.setCalloutVisibilities(ids, [options])

Sets the visibility of callouts. Callouts whose UUIDs are in the provided array will be made visible; all other callouts will be hidden. An empty array hides every callout.

Call it after asset_load_finish; a call made while the asset is still loading is dropped.
It applies to the callouts that exist at the time of the call. A callout created afterwards is visible until you call it again.

Kind: instance method of Viewer Category: Methods

Param	Type	Description
ids	`Array.<string>`	An array of callout ids that should be visible.
[options]	`Object`	Options for controlling how the ids are interpreted.
[options.matchField]	`"uuid"` \| `"externalId"`	Which field the ids refer to: `uuid` by default, or `externalId` to key by your own ids.

Example

// Show only two specific callouts, hiding all others
viewer.setCalloutVisibilities(["2997a059-f937-40c7-b4f3-42431f2b4f2b", "a1b2c3d4-e5f6-7890-abcd-ef1234567890"]);

Example

// Show two callouts identified by their externalId, hiding all others
viewer.setCalloutVisibilities(["inspection-2026-0042", "inspection-2026-0043"], { matchField: "externalId" });

Example

// Hide all callouts
viewer.setCalloutVisibilities([]);

viewer.setCalloutOverrides(overrides, [options])

Applies transient per-callout overrides, such as a temporary callout color. Pass a map keyed by callout UUID, where each value is an ICalloutOverrideData object.

Behavior

Transient: Overrides are never persisted. Nothing is written to the asset, and other users who load the asset later will not see them.
Lost on session restart: If the rendering session restarts, for example after an idle timeout, the overrides are gone and the persisted colors apply again.
Partial merge: Only the callouts named in the map are affected. Callouts that are not mentioned keep the overrides they already have.
Lasts for the rest of the rendering session: Once set, a callout's override color can only be changed by another setCalloutOverrides call.
Protected: An overridden callout is protected from persisted color changes. A persisted update made within the current session (an updateCallout call with viewColor) does not affect the displayed color of an overridden callout for the rest of the rendering session, though its other persisted fields, such as title, still apply. The IViewState calloutBgColorOverride session state, if set, still takes precedence over per-callout colors.

Kind: instance method of Viewer Category: Methods

Param	Type	Description
overrides	`Object.<string, NiraAPI.ICalloutOverrideData>`	A map of callout uuid or externalId to the overrides for that callout.
[options]	`Object`	Options for controlling how the map's keys are interpreted.
[options.matchField]	`"uuid"` \| `"externalId"`	Which field the overrides map's keys refer to: `uuid` by default, or `externalId` to key by your own ids.

Example

// Temporarily show one callout in red and another in green
viewer.setCalloutOverrides({
  "2997a059-f937-40c7-b4f3-42431f2b4f2b": { viewColor: [255, 0, 0] },
  "a1b2c3d4-e5f6-7890-abcd-ef1234567890": { viewColor: [0, 255, 0] },
});

Example

// Temporarily show a callout identified by its externalId in red
viewer.setCalloutOverrides({ "inspection-2026-0042": { viewColor: [255, 0, 0] } }, { matchField: "externalId" });

viewer.selectObject(objectName, sceneName)

Selects an object by name.

Kind: instance method of Viewer Category: Methods

Param	Type	Description
objectName	`string`	Name of the object, e.g. "teapot01".
sceneName	`string`	Optional scene name of the object to select, e.g. "teapot01.obj". If not specified, the first object found that matches the objectName will be selected, regardless of its sceneName.

Example

// Select the object named 'teapot01' in any scene.
viewer.selectObject("teapot01");

Events

"asset_unload"

Emitted when an asset is unloaded (e.g. due to idle timeout).

Kind: event emitted by Viewer Category: Events

"object_picked"

Emitted when an object is picked in the 3D view.

A common use case for this event is to present some custom user interface related to something that the user clicked on. The value of the objectName, sceneName, and/or matName properties can be used as a lookup key to retrieve relevant information from your own datasources to populate your UI.

To receive the object_picked event, either the enableObjectPicking or the useMeshesForTagging view option must be set to true.

Kind: event emitted by Viewer Category: Events
Properties

Name	Type	Description
objectType	`string`	The type of object. Currently, only "mesh" is supported.
objectName	`string`	The name of the object that was picked.
sceneName	`string`	The scene name of the object that was picked, if applicable. (e.g. "my-scene.obj")
matName	`string`	The material name that was picked, if applicable.

Example

// Create a Viewer instance and enable object picking,
// which is required to receive object_picked events.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "enableObjectPicking": true,
});
// Register to receive object_picked events.
viewer.on("object_picked", (objectInfo) => {
  console.log("object was picked:", objectInfo.objectName);
});

"view_steady"

Emitted when the 3D view becomes steady after being moved or changed.

After an asset loads, asset_load_finish fires first, followed by exactly one view_steady carrying the callouts of the loaded asset. After that, view_steady fires again whenever any callout's position in the list or any of its fields changes, for example after camera movement, a clipping change or setCalloutVisibilities.

Kind: event emitted by Viewer Category: Events
Properties

Name	Type	Description
orderedCallouts	`Array.<object>`	A list of callout info objects in order of their closeness to the current 3D viewpoint. Note, this list only includes information about 3D point callouts. It does not include polyline-based based callouts such as measurements.
orderedCallouts[].uuid	`string`	The uuid of the callout.
orderedCallouts[].alphanumericId	`string`	The id of the callout in alphanumeric form (A1, A2, ..., B3, etc).
orderedCallouts[].isVisible	`boolean`	Whether the callout is currently shown in the 3D view. This is true only when the callout is not hidden (in the explorer panel or with `setCalloutVisibilities`), `isWithinView` is true and `isClipped` is false. This does not account for objects in front of the callout, so a callout covered by the model still reports true, even though with a `calloutOcclusionStyle` of `Hidden` (the default) it is not drawn.
orderedCallouts[].distance	`number`	Distance of the callout from the current 3D viewpoint.
orderedCallouts[].isWithinView	`boolean`	Whether the callout is inside the current camera's view. This does not account for objects in front of the callout, so a callout that is within view can still be covered by the model.
orderedCallouts[].isClipped	`boolean`	true when a Clipping Volume is active and the callout is outside it.

"clipping_volume_changed"

Emitted when any clipping volume parameter of the view state changes, whatever the cause. For example:

The user moves, resizes or rotates the box in the 3D view. The event fires once the user releases the handle, not during the drag.
The user changes the Clipping Volume options in the View Settings menu.
A setSessionState or setClippingVolume call changes a clipping parameter.

It also fires once when each asset loads, with the clipping volume of that asset.

The payload is an IClippingVolume object, the same shape that getClippingVolume resolves with.

Kind: event emitted by Viewer Category: Events
Example

viewer.on("clipping_volume_changed", (volume) => {
  console.log("Clipping enabled:", volume.clippingEnabled);
  console.log("Box center:", volume.clippingTranslate, "half-extents:", volume.clippingScale);
});

"access_renewal_needed"

Emitted shortly before the signed URL of the embedded asset expires, so that you can supply a new one. It can fire more than once for the same expiry, for example when the browser tab becomes visible again.

Fetch a new signed URL for the same asset and level from your backend and pass it to renewAccess.

Kind: event emitted by Viewer Category: Events
Properties

Name	Type	Description
exp	`number`	The expiry time of the current URL, in seconds since the epoch.

Example

viewer.on("access_renewal_needed", async ({ exp }) => {
  const newUrl = await fetch("/my-backend/new-nira-url").then((r) => r.text());
  await viewer.renewAccess(newUrl);
});

"access_expired"

Emitted when the signed URL of the embedded asset can no longer be used.

The reason is one of:

expired: the URL passed its expiry time. This is the only reason for which you should sign a new URL and set it as the iframe src.
invalid: something is wrong with the URL itself, for example its signature, its claims, an expiry more than 4 hours away, or a signing key that was deleted.
forbidden: the URL is valid but access is refused, for example because the asset is no longer available or the feature is not enabled for your organization.
rate_limited: too many requests were made with this URL or for your organization in a short time.

At most 3 of these events are delivered per 60 seconds. Further events in that period are dropped.

Kind: event emitted by Viewer Category: Events
Properties

Name	Type	Description
reason	`string`	One of `expired`, `invalid`, `forbidden` or `rate_limited`.

Example

viewer.on("access_expired", ({ reason }) => {
  if (reason === "expired") {
    fetch("/my-backend/new-nira-url").then((r) => r.text()).then((url) => {
      document.getElementById("niraviewer").src = url;
    });
  }
});

"callout_deleted"

Emitted when a callout is deleted by the user.

Kind: event emitted by Viewer Category: Events
Properties

Name	Type	Description
uuid	`string`	The UUID of the deleted callout.
[externalId]	`string`	The externalId of the deleted callout, if one is set. Undefined otherwise.
isOriginator	`boolean`	true when the callout was deleted within the current viewing session, false if the callout was deleted using a different viewing session. Check if this is true if you have code that should only run within the context of the viewing session that deleted the callout.

"callout_created"

Emitted when a callout is created by the user.

Kind: event emitted by Viewer Category: Events
Properties

Name	Type	Description
uuid	`string`	The UUID of the created callout.
title	`string`	The title of the activated callout.
alphanumericId	`string`	The alphanumeric ID of the created callout, as shown in the viewer (e.g. "A1").
[externalId]	`string`	The externalId of the created callout, if one is set. Undefined otherwise.
isOriginator	`boolean`	true when the callout was created within the current viewing session, false if the callout was created using a different viewing session. Check if this is true if you have code that should only run within the context of the viewing session that created the callout.
calloutUuid	`string`	The UUID of the created callout (legacy, do not use).

"callout_activated"

Emitted when a callout is activated (selected) by the user.

Kind: event emitted by Viewer Category: Events
Properties

Name	Type	Description
uuid	`string`	The UUID of the activated callout.
title	`string`	The title of the activated callout.
alphanumericId	`string`	The alphanumeric ID of the activated callout, as shown in the viewer (e.g. "A1").
[externalId]	`string`	The externalId of the activated callout, if one is set. Undefined otherwise.
calloutUuid	`string`	The UUID of the created callout (legacy, do not use).

"asset_load_start"

Emitted when an asset starts loading.

Kind: event emitted by Viewer Category: Events
Properties

Name	Type	Description
assetUuid	`string`	The UUID of the asset being loaded.

"toolmode"

Emitted when the tool mode is changed.

Kind: event emitted by Viewer Category: Events
Properties

Name	Type	Description
toolmode	`string`	The current tool mode.

"asset_load_finish"

Emitted when an asset finishes loading.

This event is emitted before any view_steady event for the loaded asset. Exactly one view_steady, carrying the callouts of the loaded asset, follows it.

Kind: event emitted by Viewer Category: Events
Properties

Name	Type	Description
assetUuid	`string`	The UUID of the asset that finished loading.

NiraAPI.Toolmode : `enum`

A Nira tool mode. Pass one of these values when setting the toolmode using the setToolMode function.

Kind: static enum of NiraAPI Read only: true
Properties

Name	Description
NiraAPI.Toolmode.Select	Toolmode for selecting.
NiraAPI.Toolmode.Fps	Toolmode for fps.
NiraAPI.Toolmode.Orbit	Toolmode for orbiting.
NiraAPI.Toolmode.Pan	Toolmode for panning.
NiraAPI.Toolmode.Zoom	Toolmode for zooming.
NiraAPI.Toolmode.Measure	Toolmode for measuring.
NiraAPI.Toolmode.Callout	Toolmode for callout.

Example

viewer.setToolMode(NiraAPI.Toolmode.Fps);

NiraAPI.IViewOptions

Options that control the behavior of the Nira embed. These parameters should be included in the object passed as the second parameter to the Viewer constructor. Many of these options can also be specified on a per-asset basis using the View mode options dialog

Kind: static interface of NiraAPI Example

// Create a Viewer instance attached to an iframe with ID "nira-iframe" and set a few options.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showNavigationTools": false,
  "showMeasureTool": false,
  "suppressCalloutDialog": true,
});

IViewOptions.showNavigationTools : `boolean`

Whether to show Nira's built-in navigation toolbar on the left side of the UI. This is useful if you're providing your own navigation UI, or if you'd prefer not to have buttons for switching between navigation modes. When this is set to false, individual tool visibility options (e.g. showOrbitTool) have no effect.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide its navigation tool buttons
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showNavigationTools": false,
});

IViewOptions.showCalloutTool : `boolean`

Whether to show Nira's callout tool button on the left side of the UI. Setting this to false is useful if you're providing your own buttons to switch into callout creation mode.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide its callout tool button.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showCalloutTool": false,
});

IViewOptions.showMeasureTool : `boolean`

Whether to show Nira's measurement tool button on the left side of the UI. Setting this to false is useful if you're providing your own buttons to switch into and out of measurement creation mode.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide its measure tool button.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showMeasureTool": false,
});

IViewOptions.showCalloutsList : `boolean`

Whether to show the Layer List button in the lower right corner. The Layer List allows viewers to see annotations in a list and control the visibility of the 2D Map and 3D Models. Setting this to false is useful if you're providing your own listing UI.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide its callout list button.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showCalloutsList": false,
});

IViewOptions.showRenderModes : `boolean`

Whether to show Nira's render mode toggles in the View Settings menu (lower right corner). Render mode toggles include Matcap and X-Ray modes.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide its render mode toggles.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showRenderModes": false,
});

IViewOptions.suppressCalloutDialog : `boolean`

Whether to suppress the display of Nira's built-in callout dialog when a callout is activated. Setting this to true is useful if you're providing your own UI for the display of callout related information.

Kind: static property of IViewOptions Default: false
Example

// Create a Viewer instance and supress the built-in callout dialog.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "suppressCalloutDialog": true,
});

IViewOptions.useMeshesForTagging : `boolean`

Causes meshes within the asset to be used for the special purpose of tagging point cloud regions.

This requires a both a mesh and a point cloud to be uploaded to the same asset. The mesh should contain separate objects with each object encapsulating a portion of the point cloud. These encapsulating objects are typically created using an engineering or CAD application then exported to mesh file (e.g. .OBJ).

When useMeshesForTagging is true, all meshes in the asset will be invisible by default. When a mesh is picked by the user, it will become visible on top of the point cloud with a vibrant color in a slightly transparent style, which will cause that region of the point cloud to appear highlighted.

If you have registered as a listener on the "object_picked" event, you will receive a mesh object's information every time one is picked by the user. The object's name can then be used as a lookup key to display relevant information from your own data sources or perform other custom actions. See the object_picked event for more information.

Please note, the enableObjectPicking view option will automatically be set to true when useMeshesForTagging is true.

Kind: static property of IViewOptions Default: false
Example

// Create a Viewer instance and use meshes within the asset for the special purpose
// of tagging point cloud regions.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "useMeshesForTagging": true,
});

IViewOptions.enableObjectPicking : `boolean`

By default, selecting an object is not possible while in any of Nira's navigation tools. Setting enableObjectPicking to true allows a single click or tap (i.e. a pick) of an object in the 3D view to select it while in a navigation tool.

Additionally, if you are listening for object_picked events, you will receive an object's name any time one is picked. This object's name can then be used as a lookup key to display relevant information from your own data sources or perform other custom actions.

Kind: static property of IViewOptions Default: false
Example

// Create a Viewer instance and enable object picking.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "enableObjectPicking": true,
});

IViewOptions.showOrbitTool : `boolean`

Whether to show the Orbit navigation tool button in the toolbar. This is a sub-option of showNavigationTools — if showNavigationTools is false, this option has no effect.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide the orbit tool button.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showOrbitTool": false,
});

IViewOptions.showPanTool : `boolean`

Whether to show the Pan navigation tool button in the toolbar. This is a sub-option of showNavigationTools — if showNavigationTools is false, this option has no effect.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide the pan tool button.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showPanTool": false,
});

IViewOptions.showZoomTool : `boolean`

Whether to show the Zoom navigation tool button in the toolbar. This is a sub-option of showNavigationTools — if showNavigationTools is false, this option has no effect.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide the zoom tool button.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showZoomTool": false,
});

IViewOptions.showTeleportTool : `boolean`

Whether to show the Teleport navigation tool button in the toolbar. This is a sub-option of showNavigationTools — if showNavigationTools is false, this option has no effect.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide the teleport tool button.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showTeleportTool": false,
});

IViewOptions.showFpsTool : `boolean`

Whether to show the FlyCam (first-person) navigation tool button in the toolbar. This is a sub-option of showNavigationTools — if showNavigationTools is false, this option has no effect.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide the FlyCam tool button.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showFpsTool": false,
});

IViewOptions.showPanoCamTool : `boolean`

Whether to show the PanoCam navigation tool button in the toolbar. The PanoCam tool is only available for assets that contain point cloud data. This is a sub-option of showNavigationTools — if showNavigationTools is false, this option has no effect.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide the PanoCam tool button.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showPanoCamTool": false,
});

IViewOptions.defaultNavigationTool : `string`

Which navigation tool to activate by default when the asset loads. Valid values are "orbit", "pan", "zoom", "teleport", "flyCam", and "panoCam".

Kind: static property of IViewOptions Default: "orbit"
Example

// Create a Viewer instance that starts in pan mode.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "defaultNavigationTool": "pan",
});

IViewOptions.showFullscreenButton : `boolean`

Whether to show the fullscreen button in the top-right part of the viewer.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide the fullscreen button.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showFullscreenButton": false,
});

IViewOptions.showAssetName : `boolean`

Whether to show the asset name above the thumbnail preview image during loading.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide the asset name.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showAssetName": false,
});

IViewOptions.showTriangleAndTextureSize : `boolean`

Whether to show asset stats (triangle count, texture size, splat count, point count) while the asset is loading.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide asset stats during loading.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showTriangleAndTextureSize": false,
});

IViewOptions.showViewSettings : `boolean`

Whether to show the View Settings button in the lower right corner. The View Settings menu lets viewers toggle common view settings such as Annotations, Matcap shading mode, and Clipping Volumes. See also showRenderModes.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide the View Settings button.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showViewSettings": false,
});

IViewOptions.showDayNightRain : `boolean`

Whether to show the Environment Light toggle button in the lower right corner. This lets viewers adjust the environment background and lighting.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide the environment light toggle.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showDayNightRain": false,
});

IViewOptions.showGeomTypeChooser : `boolean`

Whether to show the Geometry Type control in the lower right corner. This lets viewers switch between 3D Textured Mesh, Point Cloud, and 3D Gaussian Splat for assets that have multiple geometry types available.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and hide the geometry type chooser.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "showGeomTypeChooser": false,
});

IViewOptions.allowShowCameras : `boolean`

Whether to allow viewers to see the position and orientation of cameras. The toggle option is available within the Photo Strip.

Kind: static property of IViewOptions Default: true
Example

// Create a Viewer instance and prevent viewers from seeing camera positions.
const viewer = new NiraAPI.Viewer("nira-iframe", {
  "allowShowCameras": false,
});

NiraAPI.IViewState

View State parameters. Any combination of these parameters can be included in the object passed to the setSessionState function.

Kind: static interface of NiraAPI

IViewState.explode : `number`

A factor that "explodes" or offsets individual parts of the model for inspection.

Kind: static property of IViewState Default: 0.0
Example

// Slightly explode the model:
viewer.setSessionState({ explode: 0.2 });

IViewState.gridSize : `number`

The size of the 3D grid spacing.

Kind: static property of IViewState Default: 1.0
Example

// Double the grid spacing:
viewer.setSessionState({ gridSize: 2.0 });

IViewState.gridNumLines : `number`

The number of lines (in each direction) drawn in the 3D grid.

Kind: static property of IViewState Default: 8
Example

// Increase grid lines to 16:
viewer.setSessionState({ gridNumLines: 16 });

IViewState.gridDraw : `boolean`

Whether to display a 3D grid in the scene.

Kind: static property of IViewState Default: false
Example

// Show the 3D grid:
viewer.setSessionState({ gridDraw: true });

IViewState.envName : `string`

The name of an environment map or background texture.

Kind: static property of IViewState Example

// Use the 'Circus Maximus 1' environment map:
viewer.setSessionState({ envName: 'Circus Maximus 1' });

IViewState.envExposure : `number`

Exposure compensation for the environment lighting.

Kind: static property of IViewState Default: 0.0
Example

// Increase environment brightness:
viewer.setSessionState({ envExposure: 1.5 });

IViewState.envRotY : `number`

Rotation of the environment map around the Y-axis (in degrees).

Kind: static property of IViewState Default: 0.0
Example

// Rotate environment by 45 degrees:
viewer.setSessionState({ envRotY: 45.0 });

IViewState.bgType : `"Color"` | `"Environment"`

Indicates whether the background is a solid color or an environment map.

Kind: static property of IViewState Default: "Color"
Example

// Use an environment map instead of a solid color:
viewer.setSessionState({ bgType: 'Environment' });

IViewState.bgColor : `object`

The solid background color if bgType is "Color".

Kind: static property of IViewState Properties

Name	Type	Default
x	`number`	`0.0`
y	`number`	`0.0`
z	`number`	`0.0`

Example

// Set the background color to light gray:
viewer.setSessionState({
  bgType: 'Color',
  bgColor: { x: 0.8, y: 0.8, z: 0.8 }
});

IViewState.wfColor : `object`

The color used for wireframe overlays.

Kind: static property of IViewState Properties

Name	Type	Default
x	`number`	`0.0`
y	`number`	`0.0`
z	`number`	`0.0`

Example

// Give wireframes a bright red color:
viewer.setSessionState({
  wfColor: { x: 1.0, y: 0.0, z: 0.0 }
});

IViewState.wfThickness : `number`

The thickness of wireframe lines.

Kind: static property of IViewState Default: 1.0
Example

// Make wireframe lines thicker:
viewer.setSessionState({ wfThickness: 2.0 });

IViewState.renderTextures : `boolean`

Whether textures are rendered on objects.

Kind: static property of IViewState Default: true
Example

// Disable texture rendering:
viewer.setSessionState({ renderTextures: false });

IViewState.renderFacetedNormals : `boolean`

Whether to render geometry with faceted normals (hard edges).

Kind: static property of IViewState Default: true
Example

// Switch to smooth shading:
viewer.setSessionState({ renderFacetedNormals: false });

IViewState.renderAo : `boolean`

Whether ambient occlusion (AO) is rendered.

Kind: static property of IViewState Default: true
Example

// Turn off ambient occlusion:
viewer.setSessionState({ renderAo: false });

IViewState.renderTriangulatedWf : `boolean`

Whether wireframes show the triangulation of meshes.

Kind: static property of IViewState Default: true
Example

// Show only quadrilateral (and ngon > 4) edges:
viewer.setSessionState({ renderTriangulatedWf: false });

IViewState.coordSystem : `"Yup"` | `"Zup"`

Defines the coordinate system convention (Y-up or Z-up).

Kind: static property of IViewState Default: "Yup"
Example

// Switch to Z-up:
viewer.setSessionState({ coordSystem: 'Zup' });

IViewState.measurementPrecision : `number`

How many decimal places to show for measurement labels.

Kind: static property of IViewState Default: 2
Example

// Show 4 decimals for measurements:
viewer.setSessionState({ measurementPrecision: 4 });

IViewState.measurementDrawAxisLines : `boolean`

If true, renders additional axis lines for measurement references.

Kind: static property of IViewState Default: false
Example

// Enable measurement axis lines:
viewer.setSessionState({ measurementDrawAxisLines: true });

IViewState.animFrame : `number`

Current animation frame index or time.

Kind: static property of IViewState Default: 0.0
Example

// Jump to animation frame 10:
viewer.setSessionState({ animFrame: 10 });

IViewState.envBlur : `number`

Controls how blurred the environment texture is when rendered.

Kind: static property of IViewState Default: 0.0
Example

// Slightly blur environment reflections:
viewer.setSessionState({ envBlur: 0.25 });

IViewState.renderTaa : `boolean`

Whether temporal anti-aliasing (TAA) is enabled.

Kind: static property of IViewState Default: true
Example

// Disable TAA:
viewer.setSessionState({ renderTaa: false });

IViewState.renderBloom : `boolean`

Whether bloom is applied for bright highlights.

Kind: static property of IViewState Default: true
Example

// Turn off bloom:
viewer.setSessionState({ renderBloom: false });

IViewState.vignette : `number`

Vignette effect strength around the viewport edges.

Kind: static property of IViewState Default: 0.0
Example

// Mild vignette:
viewer.setSessionState({ vignette: 0.2 });

IViewState.dithering : `number`

Dithering amount used to reduce banding in gradients.

Kind: static property of IViewState Default: 0.0
Example

// Slight dithering:
viewer.setSessionState({ dithering: 0.1 });

IViewState.camUp : `object`

A vector representing the camera's up direction.

Kind: static property of IViewState Properties

Name	Type	Default
x	`number`	`0.0`
y	`number`	`0.0`
z	`number`	`0.0`

Example

// Switch the camera up direction to (0,0,1):
viewer.setSessionState({
  camUp: { x: 0, y: 0, z: 1 }
});

IViewState.renderUseMipmaps : `boolean`

Whether textures use mipmaps for improved rendering performance.

Kind: static property of IViewState Default: true
Example

// Disable mipmaps:
viewer.setSessionState({ renderUseMipmaps: false });

IViewState.envGroundProj : `boolean`

If true, attempts to project the environment onto a ground plane.

Kind: static property of IViewState Default: false
Example

viewer.setSessionState({ envGroundProj: true });

IViewState.version : `number`

A version number for forward/backward compatibility checks.

Kind: static property of IViewState Default: 6
Example

viewer.setSessionState({ version: 7 });

IViewState.useSingleMat : `boolean`

If true, uses a single material for all geometry (for special rendering modes).

Kind: static property of IViewState Default: false
Example

// Force a single material:
viewer.setSessionState({ useSingleMat: true });

IViewState.noMipmapGen : `boolean`

Prevents automatic generation of mipmaps if true.

Kind: static property of IViewState Default: false
Example

viewer.setSessionState({ noMipmapGen: true });

IViewState.animFps : `number`

The frames per second for any animation or time-based updates.

Kind: static property of IViewState Default: 30
Example

// Lower the FPS for a slower animation rate:
viewer.setSessionState({ animFps: 15 });

IViewState.lighting : `boolean`

Whether scene lighting is enabled.

Kind: static property of IViewState Default: true
Example

// Switch to an unlit mode:
viewer.setSessionState({ lighting: false });

IViewState.matCapName : `string`

The name of a matcap (material capture) texture used for specialized shading.

Kind: static property of IViewState Example

viewer.setSessionState({ matCapName: 'chromeStyle' });

IViewState.renderVertexColors : `boolean`

Whether per-vertex colors are rendered.

Kind: static property of IViewState Default: true
Example

// Disable vertex colors:
viewer.setSessionState({ renderVertexColors: false });

IViewState.showCallouts : `boolean`

If true, callouts (labels, notes) are displayed in the scene.

Kind: static property of IViewState Default: true
Example

// Hide callouts:
viewer.setSessionState({ showCallouts: false });

IViewState.showMeasurements : `boolean`

Whether to display measurement lines and labels in the scene.

Kind: static property of IViewState Default: true
Example

// Disable measurement overlays:
viewer.setSessionState({ showMeasurements: false });

IViewState.globalRotX : `number`

Global rotation around the X-axis applied to all scene objects.

Kind: static property of IViewState Default: 0.0
Example

viewer.setSessionState({ globalRotX: 45.0 });

IViewState.globalRotY : `number`

Global rotation around the Y-axis applied to all scene objects.

Kind: static property of IViewState Default: 0.0
Example

viewer.setSessionState({ globalRotY: 180.0 });

IViewState.globalRotZ : `number`

Global rotation around the Z-axis applied to all scene objects.

Kind: static property of IViewState Default: 0.0
Example

viewer.setSessionState({ globalRotZ: 90.0 });

IViewState.sharpen : `number`

A factor controlling any post-process sharpening.

Kind: static property of IViewState Default: 0.5
Example

// Increase sharpening:
viewer.setSessionState({ sharpen: 1.0 });

IViewState.renderMode : `string`

A human-readable string for the render mode (e.g., "Shaded", "Wireframe").

Kind: static property of IViewState Example

viewer.setSessionState({ renderMode: 'Wireframe' });

IViewState.renderModeColor : `object`

The color used when renderMode is set to a single color shading mode.

Kind: static property of IViewState Properties

Name	Type	Default
x	`number`	`0.0`
y	`number`	`0.0`
z	`number`	`0.0`

Example

// Shade everything in green:
viewer.setSessionState({
  renderMode: 'SingleColor',
  renderModeColor: { x: 0.0, y: 1.0, z: 0.0 }
});

IViewState.nodeVisibility : `Array.<NodeVisibility>`

A list that controls visibility of specific scene nodes.

Kind: static property of IViewState Example

viewer.setSessionState({
  nodeVisibility: [
    { objectName: 'foliage', sceneName: 'scene1' },
    { objectName: 'carBody' }
  ]
});

IViewState.renderDof : `boolean`

Whether depth of field (DoF) is simulated.

Kind: static property of IViewState Default: true
Example

// Turn off depth of field:
viewer.setSessionState({ renderDof: false });

IViewState.showAreas : `boolean`

If true, areas or region-specific outlines are displayed.

Kind: static property of IViewState Default: true
Example

// Hide area outlines:
viewer.setSessionState({ showAreas: false });

IViewState.cameraLimitsPanning : `boolean`

Enables or disables camera panning limits.

Kind: static property of IViewState Default: false
Example

viewer.setSessionState({ cameraLimitsPanning: true });

IViewState.aoRadius : `number`

The radius used in ambient occlusion calculations.

Kind: static property of IViewState Default: 0.38
Example

// Increase AO radius for deeper shadows:
viewer.setSessionState({ aoRadius: 0.5 });

IViewState.cameraLimitsZoomMin : `number`

The minimum camera zoom (or distance) limit.

Kind: static property of IViewState Default: 0.0
Example

viewer.setSessionState({ cameraLimitsZoomMin: 5.0 });

IViewState.cameraLimitsZoomMax : `number`

The maximum camera zoom (or distance) limit.

Kind: static property of IViewState Default: 0.0
Example

viewer.setSessionState({ cameraLimitsZoomMax: 50.0 });

IViewState.aoIntensity : `number`

The strength of the ambient occlusion effect.

Kind: static property of IViewState Default: 0.38
Example

viewer.setSessionState({ aoIntensity: 0.8 });

IViewState.cameraLimitsBottom : `boolean`

If true, restricts the camera from going below a certain "floor."

Kind: static property of IViewState Default: false
Example

viewer.setSessionState({ cameraLimitsBottom: true });

IViewState.cameraLimitsPanningPos : `object`

A position used as a reference when applying panning limits.

Kind: static property of IViewState Properties

Name	Type	Default
x	`number`	`0.0`
y	`number`	`0.0`
z	`number`	`0.0`

Example

viewer.setSessionState({
  cameraLimitsPanningPos: { x: 10, y: 0, z: 10 }
});

IViewState.clippingEnabled : `boolean`

Whether the clipping volume is applied to the scene.

The clipping volume is an oriented box defined by clippingTranslate (its center), clippingRotate (its orientation) and clippingScale (its half-extents). When enabled, only the portion of the scene that falls inside that box is displayed: meshes, point clouds, splats and 3D tiles are cut away outside of it, and callouts, measurements and scan stations whose position falls outside of it are hidden.

A clipping volume is only applied once its position has been established, either by the user having positioned it in the viewer, or by having supplied clippingTranslate (usually together with clippingScale) via setSessionState. Enabling clipping on a session where the volume has never been positioned has no visible effect.

In the viewer UI, this corresponds to the "Clipping Volume" checkbox in the View Settings menu.

Kind: static property of IViewState Default: false
Example

// Enable a clipping volume and place it in one call.
// This shows a 4 x 4 x 20 (world units) slab centered a little below and in front of the origin:
viewer.setSessionState({
  clippingEnabled: true,
  clippingTranslate: { x: 0, y: -1.5, z: -9.75 },
  clippingRotate: { x: 0, y: 0, z: 0 },
  clippingScale: { x: 2, y: 2, z: 10 },
});

Example

// Turn clipping back off. The volume's position, orientation and size are retained,
// so setting clippingEnabled back to true will restore the same volume:
viewer.setSessionState({ clippingEnabled: false });

Example

// Toggle between predefined clipping "presets", e.g. from a dropdown:
const clippingPresets = {
  floor1: { clippingScale: { x: 50, y: 0.25, z: 50 }, clippingTranslate: { x: 0, y: 3, z: 0 } },
  floor2: { clippingScale: { x: 50, y: 0.25, z: 50 }, clippingTranslate: { x: 0, y: 6, z: 0 } },
};
viewer.setSessionState({ ...clippingPresets.floor2, clippingEnabled: true });

IViewState.clippingDraw : `boolean`

Whether the clipping volume's box outline and its interactive handles are drawn.

When true, the box is drawn as a stippled wireframe and the user is able to resize it by dragging its bounds handles (and, if clippingGizmo is non-zero, to move and rotate it). When false, the scene is still clipped, but the box itself is invisible and cannot be manipulated by the user.

This has no effect unless clippingEnabled is true. In the viewer UI, this corresponds to the "Edit" checkbox underneath "Clipping Volume" in the View Settings menu.

Kind: static property of IViewState Default: true
Example

// Clip the scene, but hide the clip box outline and prevent the user from adjusting it:
viewer.setSessionState({
  clippingEnabled: true,
  clippingDraw: false,
});

Example

// Show the clip box outline and its resize handles again:
viewer.setSessionState({ clippingDraw: true });

IViewState.clippingScale : `object`

The half-extents of the clipping volume, along the volume's own (rotated) axes.

The volume is a box spanning -1 to +1 in each axis of its local space, so these values are half sizes: the box's full size in world units is 2 * x by 2 * y by 2 * z. The scale is applied before clippingRotate and clippingTranslate.

Kind: static property of IViewState Properties

Name	Type
x	`number`
y	`number`
z	`number`

Example

// A 4 x 4 x 4 world unit cube:
viewer.setSessionState({
  clippingScale: { x: 2, y: 2, z: 2 }
});

Example

// A thin horizontal slab, useful for looking at a single floor of a building.
// 100 x 0.5 x 100 world units, centered 3 units above the origin:
viewer.setSessionState({
  clippingEnabled: true,
  clippingScale: { x: 50, y: 0.25, z: 50 },
  clippingTranslate: { x: 0, y: 3, z: 0 },
});

IViewState.clippingRotate : `object`

The rotation of the clipping volume, in degrees.

The three values are euler angles applied about the X, then Y, then Z axis. Rotation is applied around the volume's center (clippingTranslate).

Kind: static property of IViewState Properties

Name	Type	Default
x	`number`	`0.0`
y	`number`	`0.0`
z	`number`	`0.0`

Example

// Tilt the clipping volume 15 degrees about the X axis:
viewer.setSessionState({
  clippingRotate: { x: 15, y: 0, z: 0 }
});

Example

// An axis aligned volume. Note that these are degrees, not radians:
viewer.setSessionState({
  clippingRotate: { x: 0, y: 0, z: 0 }
});

IViewState.clippingTranslate : `object`

The world space position of the center of the clipping volume.

Supplying this (usually together with clippingScale) is what establishes the volume's position for a session that has never had one positioned. See clippingEnabled.

Kind: static property of IViewState Properties

Name	Type	Default
x	`number`	`0.0`
y	`number`	`0.0`
z	`number`	`0.0`

Example

viewer.setSessionState({
  clippingTranslate: { x: 0, y: -1, z: 0 }
});

Example

// Step the volume along the Z axis to reveal successive cross sections of the model:
const sliceAt = (z) => viewer.setSessionState({
  clippingEnabled: true,
  clippingDraw: false,
  clippingScale: { x: 20, y: 20, z: 0.5 },
  clippingRotate: { x: 0, y: 0, z: 0 },
  clippingTranslate: { x: 0, y: 0, z },
});

sliceAt(-10);

IViewState.clippingGizmo : `number`

Whether the move and rotate handles are shown on the clipping volume, in addition to its resize handles.

A value of 0 gives the user resize handles only. Any non-zero value (1 is what the viewer's own UI uses) additionally displays translate and rotate handles on the volume. This only has an effect when both clippingEnabled and clippingDraw are true.

In the viewer UI, this corresponds to the "Transform" checkbox underneath "Edit" in the View Settings menu.

Kind: static property of IViewState Default: 0
Example

// Let the user move and rotate the clipping volume, not just resize it:
viewer.setSessionState({
  clippingEnabled: true,
  clippingDraw: true,
  clippingGizmo: 1,
});

Example

// Resize handles only:
viewer.setSessionState({ clippingGizmo: 0 });

IViewState.bloomRadius : `number`

The radius used for bloom effect blur.

Kind: static property of IViewState Default: 12.0
Example

// Use a larger bloom radius:
viewer.setSessionState({ bloomRadius: 20 });

IViewState.bloomIntensity : `number`

The intensity of the bloom effect.

Kind: static property of IViewState Default: 0.8
Example

// Increase bloom intensity:
viewer.setSessionState({ bloomIntensity: 1.5 });

IViewState.bloomLevel : `number`

The number of iterations/levels in the bloom filter.

Kind: static property of IViewState Default: 4
Example

// More bloom passes:
viewer.setSessionState({ bloomLevel: 6 });

IViewState.measurementUnits : `"Meters"` | `"Feet"`

The default measurement unit system for displaying distances.

Kind: static property of IViewState Default: "Meters"
Example

// Switch to feet:
viewer.setSessionState({ measurementUnits: 'Feet' });

IViewState.measurementMul : `number`

A multiplier to convert from the scene's internal units to measurementUnits.

Kind: static property of IViewState Default: 1.0
Example

// If the scene is in centimeters, multiply by 0.01 for meters:
viewer.setSessionState({ measurementMul: 0.01 });

IViewState.renderTransparency : `boolean`

Whether transparent surfaces are rendered by their alpha values.

Kind: static property of IViewState Default: true
Example

// Disable transparency:
viewer.setSessionState({ renderTransparency: false });

IViewState.calloutViewStyle : `"CalloutId"` | `"Circle"` | `"Title"`

How callouts (labels) are displayed. Possible values:

CalloutId - Displays callouts as rounded rectangles containing their alphanumeric IDs (A1, A2, etc).
Circle - Displays callouts as circular markers without text inside.
Title - Displays callouts as rounded rectangles containing their textual titles.

Kind: static property of IViewState Default: "Circle"
Example

// Use circle callouts:
viewer.setSessionState({ calloutViewStyle: 'Circle' });

IViewState.calloutOcclusionStyle : `"None"` | `"Hidden"` | `"Faded"`

The visual style of callouts when they are behind something such as a mesh or a dense pointcloud. Possible values:

None - Callouts are displayed in exactly the same way whether they're behind something or not.
Hidden - Callouts are completely invisible when they are behind something.
Faded - Callouts have a darkly tinted appearance when they're behind something.

Kind: static property of IViewState Default: "Hidden"
Example

// Show callouts as more darkly tinted when they are behind an object:
viewer.setSessionState({ calloutOcclusionStyle: 'Faded' });

IViewState.calloutDeclutterStyle : `"None"` | `"SmallCircle"`

The visual style of callouts when they overlap one another on screen, for example when the 3D view is zoomed out and callouts become close together. Possible values:

None - Callouts are displayed the same way whether they would overlap one another or not.
SmallCircle - Callouts are shrunken down into small circles when they would overlap one another.

Kind: static property of IViewState Default: "SmallCircle"
Example

// Ensure callouts keep the same appearance even when they might overlap:
viewer.setSessionState({ calloutDeclutterStyle: 'None' });

IViewState.calloutBgColorOverride : `Array.<number>` | `null`

Set the background color of all callouts in the 3D view. This setting takes precedence over individual callout colors.

The array accepts [R, G, B] or [R, G, B, A] formats.
Components are normalized values from 0.0 to 1.0.
The default callout background transparency is 0.5. Providing an alpha (4th) value in the array will override this default and it is not recommended. For most use cases, stick with [R, G, B].
Pass null to turn the override off, so individual callout colors (including those set with setCalloutOverrides) are shown again.

Kind: static property of IViewState Example

// Use a red background for all callouts:
viewer.setSessionState({ calloutBgColorOverride: [1.0, 0.0, 0.0] });
// Go back to each callout's own background color:
viewer.setSessionState({ calloutBgColorOverride: null });

IViewState.calloutTextColorOverride : `Array.<number>` | `null`

Set the text color of all callouts in the 3D view.

The array accepts [R, G, B] or [R, G, B, A] formats.
Components are normalized values from 0.0 to 1.0.
The default callout text transparency is 1.0. Providing an alpha (4th) value in the array will override this default and it is not recommended. For most use cases, stick with [R, G, B].
Pass null to turn the override off, so the default callout text color is shown again.

Kind: static property of IViewState Example

// Use white text for all callouts:
viewer.setSessionState({ calloutTextColorOverride: [1.0, 1.0, 1.0] });
// Go back to the default text color:
viewer.setSessionState({ calloutTextColorOverride: null });

IViewState.cameraLimitsOrbiting : `boolean`

If true, restricts orbital camera movement to certain bounds.

Kind: static property of IViewState Default: false
Example

viewer.setSessionState({ cameraLimitsOrbiting: true });

IViewState.levelsEnabled : `boolean`

Toggles a "levels" post-processing effect.

Kind: static property of IViewState Default: false
Example

// Enable levels correction:
viewer.setSessionState({ levelsEnabled: true });

IViewState.levelsShadows : `number`

Shadows input level for the "levels" effect.

Kind: static property of IViewState Default: 0.0
Example

viewer.setSessionState({ levelsShadows: 10 });

IViewState.levelsMidtones : `number`

Midtones gamma for the "levels" effect.

Kind: static property of IViewState Default: 1.0
Example

// Darken midtones:
viewer.setSessionState({ levelsMidtones: 0.8 });

IViewState.levelsHighlights : `number`

Highlights input level for the "levels" effect.

Kind: static property of IViewState Default: 255.0
Example

viewer.setSessionState({ levelsHighlights: 220 });

IViewState.hiddenNodeViewStyle : `"Invisible"` | `"Xray"`

Determines how hidden nodes are visually treated: fully invisible or X-ray style.

Kind: static property of IViewState Example

// Show hidden nodes in X-ray:
viewer.setSessionState({ hiddenNodeViewStyle: 'Xray' });

IViewState.showScanStations : `boolean`

Whether to display scanning station markers for point cloud data.

Kind: static property of IViewState Default: true
Example

// Hide scan station markers:
viewer.setSessionState({ showScanStations: false });

IViewState.scanStationsSize : `number`

The size of each scan station marker if shown.

Kind: static property of IViewState Default: 45.0
Example

// Increase scan station markers size:
viewer.setSessionState({ scanStationsSize: 60.0 });

IViewState.showPoints : `boolean`

Whether points (in point clouds) are displayed at all.

Kind: static property of IViewState Default: true
Example

// Hide all point clouds:
viewer.setSessionState({ showPoints: false });

IViewState.showMeshes : `boolean`

Whether mesh geometry is displayed at all.

Kind: static property of IViewState Default: true
Example

// Hide all meshes:
viewer.setSessionState({ showMeshes: false });

IViewState.edl : `"Off"` | `"Low"` | `"High"`

Eye-Dome Lighting setting (off, low, or high quality).

Kind: static property of IViewState Default: "Low"
Example

// Turn off EDL:
viewer.setSessionState({ edl: 'Off' });

IViewState.pointsSize : `number`

The size of points rendered in point clouds.

Kind: static property of IViewState Default: 1.0
Example

// Increase point size:
viewer.setSessionState({ pointsSize: 2.5 });

IViewState.gapFill : `"Off"` | `"Basic"` | `"HQ"`

The gap-filling mode for rendering geometry or point clouds.

Kind: static property of IViewState Default: "HQ"
Example

// Disable gap-fill:
viewer.setSessionState({ gapFill: 'Off' });

IViewState.calloutTransitionStyle : `"None"` | `"GoToBookmark"` | `"FrameToCallout"`

Controls what happens by default when a callout is activated (i.e. selected) by a user.

Kind: static property of IViewState Default: "GoToBookmark"
Example

// Don't move the camera when a callout is activated:
viewer.setSessionState({ calloutTransitionStyle: 'None' });

NiraAPI.NodeVisibility

Controls the visibility of a specific node within a scene.

Kind: static interface of NiraAPI

NodeVisibility.objectName : `string`

The name of the node/object in the scene.

Kind: static property of NodeVisibility Example

// Hide object named 'foliage':
viewer.setSessionState({
  nodeVisibility: [{ objectName: 'foliage' }]
});

NodeVisibility.sceneName : `string`

The name of the scene. If unspecified, it applies to the objectName across all scenes.

Kind: static property of NodeVisibility Example

// Hide 'buildingA' in the 'city.obj' scene:
viewer.setSessionState({
  nodeVisibility: [{ objectName: 'buildingA', sceneName: 'cityScene.obj' }]
});

NiraAPI.IActivateCalloutOptions

Activate Callout Options Options for the activateCallout function.

Kind: static interface of NiraAPI

IActivateCalloutOptions.transitionStyle : `"None"` | `"GoToBookmark"` | `"FrameToCallout"`

Callout Transition Style. Determines what happens to the camera upon activation of the callout. Camera type (Perspective, Top, Left, etc.)

Kind: static property of IActivateCalloutOptions Default: "GoToBookmark"
Example

// Activate a callout and ensure that the camera stays in its current position:
viewer.activateCallout("39f8c2f4-2a33-4763-a47d-b23a0c782ffb", { transitionStyle: "None" });

IActivateCalloutOptions.matchField : `"uuid"` | `"externalId"`

Which field the callout argument passed to activateCallout refers to: uuid by default, or externalId to identify the callout by your own id.

Kind: static property of IActivateCalloutOptions Default: "uuid"

NiraAPI.ICameraState

Camera State parameters. A combination of these parameters can be included in the object passed to the setCameraState function. Note that some parameters only apply to certain camera types. For example, camFov is only applicable for camType "Perspective".

Kind: static interface of NiraAPI

ICameraState.camType : `"Perspective"` | `"Top"` | `"Bottom"` | `"Left"` | `"Right"` | `"Front"` | `"Back"` | `"Orthographic"`

Camera type (Perspective, Top, Left, etc.)

Kind: static property of ICameraState Default: "Perspective"
Example

// Switch the camera to a top-down view:
viewer.setCameraState({ camType: 'Top' });

ICameraState.camPos : `object`

The camera's position in 3D space. Must be expressed in the coordinate system of the originally uploaded files.

Kind: static property of ICameraState Properties

Name	Type	Default	Description
x	`number`	`0.0`	X coordinate of the camera.
y	`number`	`0.0`	Y coordinate of the camera.
z	`number`	`0.0`	Z coordinate of the camera.

Example

// Move the camera to (10, 5, 0):
viewer.setCameraState({
  camPos: { x: 10, y: 5, z: 0 }
});

ICameraState.camTar : `object`

The camera's target (look-at) point in 3D space. Must be expressed in the coordinate system of the originally uploaded files.

Kind: static property of ICameraState Properties

Name	Type	Default
x	`number`	`0.0`
y	`number`	`0.0`
z	`number`	`0.0`

Example

// Make the camera look at (5, 0, 5):
viewer.setCameraState({
  camTar: { x: 5, y: 0, z: 5 }
});

ICameraState.camPivot : `object`

The camera's target position. When the user uses the "Orbit" navigation tool, the camera will rotate around this point. Must be expressed in the coordinate system of the originally uploaded files.

Kind: static property of ICameraState Properties

Name	Type	Default
x	`number`	`0.0`
y	`number`	`0.0`
z	`number`	`0.0`

Example

// Pivot around (0,1,0)
viewer.setCameraState({
  camPivot: { x: 0, y: 1, z: 0 }
});

ICameraState.camFov : `number`

The camera's field of view (in degrees). Note, fov is only applicable when using the "Perspective" camType.

Kind: static property of ICameraState Default: 45.0
Example

// Use a wide angle lens (60 degrees):
viewer.setCameraState({ camFov: 60 });

NiraAPI.ICalloutData

Callout Data parameters.

Any combination of these parameters can be included in the object passed to the updateCallout function.

Kind: static interface of NiraAPI

ICalloutData.viewColor : `Array.<number>`

Set the color of a particular callout.

The array accepts [R, G, B] format.
Components are values from 0 to 255.

Kind: static property of ICalloutData Example

// Update a particular callout to use a red background:
viewer.updateCallout("eed40d71-9922-4aa2-9659-83e3426f3bde", { viewColor: [255, 0, 0] });

ICalloutData.defectTitle : `string`

Set the defectTitle of a particular callout.

Used when the callout is of type Defect.

Kind: static property of ICalloutData Example

viewer.updateCallout("eed40d71-9922-4aa2-9659-83e3426f3bde", { defectTitle: "Large crack" });

ICalloutData.title : `string`

Set the title of a particular callout.

Used when the callout is of type Camera Bookmark or Annotation

Kind: static property of ICalloutData Example

viewer.updateCallout("9095639a-a228-4950-8841-477938bc1201", { title: "Tree" });

ICalloutData.externalId : `string` | `null`

Set the externalId of a particular callout.

Your own identifier for the callout, up to 255 characters, unique among the callouts of an asset. Nira stores and returns it but never generates one. Pass null to clear it.

Kind: static property of ICalloutData Example

viewer.updateCallout("9095639a-a228-4950-8841-477938bc1201", { externalId: "inspection-2026-0042" });

NiraAPI.ICalloutOverrideData

Transient callout override parameters.

An object of these parameters is provided per callout uuid in the map passed to the setCalloutOverrides function.

Overrides are never persisted. See setCalloutOverrides for the full details of their lifetime and precedence.

Kind: static interface of NiraAPI

ICalloutOverrideData.viewColor : `Array.<number>`

Override the color of a particular callout without persisting the change.

The array accepts [R, G, B] format.
Components are values from 0 to 255.
Replaces the callout's displayed color until another setCalloutOverrides call changes it, or the rendering session restarts.
The IViewState calloutBgColorOverride session state, if set, still takes precedence over this.

Kind: static property of ICalloutOverrideData Example

// Temporarily show a particular callout with a red background:
viewer.setCalloutOverrides({ "eed40d71-9922-4aa2-9659-83e3426f3bde": { viewColor: [255, 0, 0] } });

NiraAPI.IClippingVolume : `object`

The clipping volume parameters of the view state.

getClippingVolume resolves with an object of this shape, and the clipping_volume_changed event carries one. The keys are the clipping keys of IViewState, so the object can be passed back to setSessionState or setClippingVolume as it is.

Kind: static typedef of NiraAPI Properties

Name	Type	Description
clippingEnabled	`boolean`	Whether the clipping volume is applied to the scene. See clippingEnabled.
clippingDraw	`boolean`	Whether the box outline and its handles are drawn. See clippingDraw.
clippingGizmo	`number`	Whether the move and rotate handles are shown. See clippingGizmo.
clippingScale	`object`	The half-extents of the box, as an object with numeric `x`, `y` and `z`, or `null` when the box has no valid value. See clippingScale.
clippingRotate	`object`	The rotation of the box in degrees, as an object with numeric `x`, `y` and `z`, or `null` when the box has no valid value. See clippingRotate.
clippingTranslate	`object`	The world space position of the center of the box, as an object with numeric `x`, `y` and `z`, or `null` when the box has no valid value. See clippingTranslate.

NiraAPI.Viewer
Constructor
- new NiraAPI.Viewer(elementOrId, options)
Methods
Events
NiraAPI.Toolmode : enum
NiraAPI.IViewOptions
NiraAPI.IViewState
NiraAPI.NodeVisibility
- NodeVisibility.objectName : string
- NodeVisibility.sceneName : string
NiraAPI.IActivateCalloutOptions
- IActivateCalloutOptions.transitionStyle : "None" | "GoToBookmark" | "FrameToCallout"
- IActivateCalloutOptions.matchField : "uuid" | "externalId"
NiraAPI.ICameraState
NiraAPI.ICalloutData
NiraAPI.ICalloutOverrideData
- ICalloutOverrideData.viewColor : Array.<number>
NiraAPI.IClippingVolume : object

NiraAPI.Viewer​

Key Features​

Plan and add-on required​

Samples​

Getting Started​

1. Include viewer.js​

2. Add an Iframe​

3. Create a Viewer Instance​

4. Call methods and handle events​

Constructor​

new NiraAPI.Viewer(elementOrId, options)​

Methods​

viewer.on(name, callback)​

viewer.off(eventName, callback)​

viewer.destroy()​

viewer.setCameraState(cameraState)​

viewer.setSessionState(state)​

viewer.getClippingVolume() ⇒ Promise.<object>​

viewer.setClippingVolume(volume)​

viewer.renewAccess(url) ⇒ Promise.<object>​

viewer.setToolMode(toolmode)​

viewer.setCalloutViewBookmark(callout, [options])​

viewer.activateCallout(callout, options)​

viewer.deleteCallout(callout, [options])​

viewer.updateCallout(callout, data, [options])​

viewer.setCalloutVisibilities(ids, [options])​

viewer.setCalloutOverrides(overrides, [options])​

Behavior​

viewer.selectObject(objectName, sceneName)​

Events​

"asset_unload"​

"object_picked"​

"view_steady"​

"clipping_volume_changed"​

"access_renewal_needed"​

"access_expired"​

"callout_deleted"​

"callout_created"​

"callout_activated"​

"asset_load_start"​

"toolmode"​

"asset_load_finish"​

NiraAPI.Toolmode : enum​

NiraAPI.IViewOptions​

IViewOptions.showNavigationTools : boolean​

IViewOptions.showCalloutTool : boolean​

IViewOptions.showMeasureTool : boolean​

IViewOptions.showCalloutsList : boolean​

IViewOptions.showRenderModes : boolean​

IViewOptions.suppressCalloutDialog : boolean​

IViewOptions.useMeshesForTagging : boolean​

IViewOptions.enableObjectPicking : boolean​

IViewOptions.showOrbitTool : boolean​

IViewOptions.showPanTool : boolean​

IViewOptions.showZoomTool : boolean​

IViewOptions.showTeleportTool : boolean​

IViewOptions.showFpsTool : boolean​

IViewOptions.showPanoCamTool : boolean​

IViewOptions.defaultNavigationTool : string​

IViewOptions.showFullscreenButton : boolean​

IViewOptions.showAssetName : boolean​

IViewOptions.showTriangleAndTextureSize : boolean​

IViewOptions.showViewSettings : boolean​

IViewOptions.showDayNightRain : boolean​

IViewOptions.showGeomTypeChooser : boolean​

IViewOptions.allowShowCameras : boolean​

NiraAPI.IViewState​

IViewState.explode : number​

IViewState.gridSize : number​

IViewState.gridNumLines : number​

IViewState.gridDraw : boolean​

IViewState.envName : string​

IViewState.envExposure : number​

IViewState.envRotY : number​

IViewState.bgType : "Color" | "Environment"​

IViewState.bgColor : object​

IViewState.wfColor : object​

IViewState.wfThickness : number​

IViewState.renderTextures : boolean​

IViewState.renderFacetedNormals : boolean​

NiraAPI.Viewer

Key Features

Plan and add-on required

Samples

Getting Started

1. Include viewer.js

2. Add an Iframe

3. Create a Viewer Instance

4. Call methods and handle events

Constructor

new NiraAPI.Viewer(elementOrId, options)

Methods

viewer.on(name, callback)

viewer.off(eventName, callback)

viewer.destroy()

viewer.setCameraState(cameraState)

viewer.setSessionState(state)

viewer.getClippingVolume() ⇒ `Promise.<object>`

viewer.setClippingVolume(volume)

viewer.renewAccess(url) ⇒ `Promise.<object>`

viewer.setToolMode(toolmode)

viewer.setCalloutViewBookmark(callout, [options])

viewer.activateCallout(callout, options)

viewer.deleteCallout(callout, [options])

viewer.updateCallout(callout, data, [options])

viewer.setCalloutVisibilities(ids, [options])

viewer.setCalloutOverrides(overrides, [options])

Behavior

viewer.selectObject(objectName, sceneName)

Events

"asset_unload"

"object_picked"

"view_steady"

"clipping_volume_changed"

"access_renewal_needed"

"access_expired"

"callout_deleted"

"callout_created"

"callout_activated"

"asset_load_start"

"toolmode"

"asset_load_finish"

NiraAPI.Toolmode : `enum`

NiraAPI.IViewOptions

IViewOptions.showNavigationTools : `boolean`

IViewOptions.showCalloutTool : `boolean`

IViewOptions.showMeasureTool : `boolean`

IViewOptions.showCalloutsList : `boolean`

IViewOptions.showRenderModes : `boolean`

IViewOptions.suppressCalloutDialog : `boolean`

IViewOptions.useMeshesForTagging : `boolean`

IViewOptions.enableObjectPicking : `boolean`

IViewOptions.showOrbitTool : `boolean`

IViewOptions.showPanTool : `boolean`

IViewOptions.showZoomTool : `boolean`

IViewOptions.showTeleportTool : `boolean`

IViewOptions.showFpsTool : `boolean`

IViewOptions.showPanoCamTool : `boolean`

IViewOptions.defaultNavigationTool : `string`

IViewOptions.showFullscreenButton : `boolean`

IViewOptions.showAssetName : `boolean`

IViewOptions.showTriangleAndTextureSize : `boolean`

IViewOptions.showViewSettings : `boolean`

IViewOptions.showDayNightRain : `boolean`

IViewOptions.showGeomTypeChooser : `boolean`

IViewOptions.allowShowCameras : `boolean`

NiraAPI.IViewState

IViewState.explode : `number`

IViewState.gridSize : `number`

IViewState.gridNumLines : `number`

IViewState.gridDraw : `boolean`

IViewState.envName : `string`

IViewState.envExposure : `number`

IViewState.envRotY : `number`

IViewState.bgType : `"Color"` | `"Environment"`

IViewState.bgColor : `object`

IViewState.wfColor : `object`

IViewState.wfThickness : `number`

IViewState.renderTextures : `boolean`

IViewState.renderFacetedNormals : `boolean`