Cognite REVEAL 3D Web Viewer

Visualize Cognite's 3D models in a web browser with WebGL.

Note: The component will by default send anonymous usage statistics. This is used to improve the 3D viewer. You can opt out from this in the Cognite3DViewer constructor.

Table of Contents

• Install
• Cognite Data Fusion
• Usage
  • Sample code
    • Add progress listeners
    • Make the model clickable
• API Reference
• Support

Prerequisites

You need to install the Cognite SDK which needs to be authenticated before loading the 3D viewer.

Install

Install the package with yarn:

yarn add @cognite/3d-viewer

or npm:

npm install @cognite/3d-viewer

Cognite Data Fusion

To be able to use this 3D viewer you need to have access to Cognite Data Fusion. You can upload 3D models using Cognite 3D ingestor, or by looking at Cognite's API documentation. You can then use this viewer to visualize the 3D model in any web-based application on desktop or mobile devices.

Usage

import { Cognite3DViewer, THREE, TWEEN } from '@cognite/3d-viewer';
//  If you are loading a local file, then just pass it in the localPath when you addModel:
const viewer = new Cognite3DViewer();
// If you are loading more than just local file, you would need to specify a sdk:
const viewer = new Cognite3DViewer({ sdk: new CogniteClient({ ... }) })
// Create three.js objects
const vector = new THREE.Vector3();
// Use TWEEN to animate e.g. the camera, see npmjs.com/package/@tweenjs/tween.js

Requirements

To be able to use this package you need the following polyfills:

• babel-polyfill

Sample code

Adding model from CDF

// The viewer will render to a canvas inside a wrapper container.
// You can specify the wrapper by setting options.domElement and passing the options argument
// to the Cognite3DViewer constructor. If not set, it will create a div element for you.
const viewer = new Cognite3DViewer({ sdk: new CogniteClient({ ... }) });

// You can then add the div to your existing DOM:
document.body.appendChild(viewer.domElement);

// At this point you will only see a black canvas.

// So let's add a 3D model:
const options = {
  modelId, // 3D model id
  revisionId, // The model's revision id
};
viewer.addModel(options).then(function(model) {
  // Move camera to look at the model
  viewer.fitCameraToModel(model, 0);
});

Adding local model

// The viewer will render to a canvas inside a wrapper container.
// You can specify the wrapper by setting options.domElement and passing the options argument
// to the Cognite3DViewer constructor. If not set, it will create a div element for you.
const viewer = new Cognite3DViewer();

// You can then add the div to your existing DOM:
document.body.appendChild(viewer.domElement);

// At this point you will only see a black canvas.

// So let's add a 3D model:
const options = {
  localPath: '...',
};
viewer.addModel(options).then(function(model) {
  // Move camera to look at the model
  viewer.fitCameraToModel(model, 0);
});

Note: You may need additional styling to the wrapper div container to make it fit your use-case. By default, the wrapper will have this style:

 {
  width: 100vw;
  height: 100vh;
}

The internal canvas will be styled to fill this wrapper.

Add progress listeners

function onProgress(progress) {
  console.log(progress);
}

function onComplete() {
  console.log('Model loaded');
}

const options = {
  modelId,
  revisionId,
  onProgress, // optional
  onComplete, // optional
};
viewer.addModel(options)...

Make the viewer clickable

• See: getBoundingBox
• See: getIntersectionFromPixel
• See: fitCameraToBoundingBox
• See: deselectAllNodes

viewer.on('click', function(event) {
  const { offsetX, offsetY } = event;
  const intersection = viewer.getIntersectionFromPixel(offsetX, offsetY);
  if (intersection !== null) {
    const { nodeId, point, model } = intersection;
    console.log('User clicked at world coordinate', point);
    // highlight the object
    model.selectNode(nodeId);
    // make the camera zoom to the object
    const boundingBox = model.getBoundingBox(nodeId);
    viewer.fitCameraToBoundingBox(boundingBox, 2000); // 2 sec
  } else {
    // Clicked outside the 3D model
    model.deselectAllNodes();
  }
});

Load saved camera position from the API

Assume you have the revision object from Cognite Data Fusion which you can get from this endpoint.

Here is a code snippet to use the saved camera position:

const { target, position } = revision.camera;
if (Array.isArray(target) && Array.isArray(position)) {
  // Create three.js objects
  const positionVector = new THREE.Vector3(...position);
  const targetVector = new THREE.Vector3(...target);
  // Apply transformation matrix
  positionVector.applyMatrix4(model.matrix);
  targetVector.applyMatrix4(model.matrix);
  // Set on viewer
  viewer.setCameraPosition(positionVector);
  viewer.setCameraTarget(targetVector);
} else {
  viewer.fitCameraToModel(model, 0);
}

API Reference

Table of Contents

• Cognite3DViewer
  • Parameters
  • Examples
  • dispose
  • domElement
  • isBrowserSupported
  • on
  • off
  • addModel
  • addObject3D
  • removeObject3D
  • setSlicingPlanes
  • getCameraPosition
  • getCameraTarget
  • setCameraPosition
  • setCameraTarget
  • fitCameraToBoundingBox
  • disableKeyboardNavigation
  • enableKeyboardNavigation
  • fitCameraToModel
  • worldToScreen
  • getIntersectionFromPixel
  • getScreenshot
• Intersection
• Cognite3DModel
  • getSubtreeNodeIds
  • getBoundingBox
  • iterateNodes
  • iterateSubtree
  • getNodeColor
  • setNodeColor
  • resetNodeColor
  • selectNode
  • deselectNode
  • deselectAllNodes
  • showNode
  • showAllNodes
  • hideAllNodes
  • hideNode

Cognite3DViewer

Cognite3DViewer is the root class of a Cognite 3D viewer. It controls all aspects of the 3D viewer.

Parameters

• options Object (optional, default {})
  • options.domElement Element? -- An existing DOM element that we will render into. This corresponds to the domElement property below.
  • options.noBackground boolean? -- Transparent background or not (optional, default false)
  • options.logMetrics boolean -- Send anonymous usage statistics. (optional, default true)
  • options.highlightColor boolean -- Highlight color of the selected objects (optional, default THREE.Color(0,0,1))
  • options.viewCube string? -- If defined then show a view cube and snap location of the view cube to this value. One of: 'topleft', 'topright', 'bottomleft', 'bottomright'.

Examples

const viewer = new Cognite3DViewer({
  noBackground: true,
  sdk: <Instance of CogniteClient>
});

dispose

• See: https://threejs.org/docs/#manual/en/introduction/How-to-dispose-of-objects

Dispose of WebGL resources. Can be used to free up memory when the viewer is no longer in use.

Examples

// Viewer is no longer in use, free up memory
viewer.dispose();

domElement

The DOM element the viewer will insert its rendering canvas into. The DOM element can be specified in the options when the viewer is created. If not specified, the DOM element will be created automatically. The DOM element cannot be changed after the viewer has been created.

isBrowserSupported

Check if the viewer supports the current browser

Examples

if (!Cognite3DViewer.isBrowserSupported()) {
  // create an error message to the user?
}

on

• See: off

Add event listener to the viewer call off to remove an event listener

Parameters

• type string -- Event type ('click' or 'cameraChange')
• func function (event:PointerEvent) -- The callback function

Examples

const onClick = event => { ... };
viewer.on('click', onClick);

viewer.on('cameraChange', (position, target) => {
  console.log('Camera changed: ', position, target);
});

off

• See: on

Remove event listener from the viewer call on to add an event listener

Parameters

• type string -- Event type ('click' or 'cameraChange')
• func function -- The callback function used in on

Examples

viewer.off('click', onClick);

addModel

Add a new 3D model to the viewer. Call fitCameraToModel to focus camera on the model after it has loaded.

Parameters

• options Object (optional, default {})
  • options.modelId number -- The model's id
  • options.revisionId number -- The model's revision id
  • options.geometryFilter { boundingBox?: THREE.Box3 } -- Filter out geometries. We currently only support bounding box filter, i.e. load only geometries inside the given bounding box.
  • options.onProgress function (progress: Object)? -- Callback for progress events
  • options.onComplete function? -- Callback when the model is fully loaded

Examples

// Load a model and focus camera on the model
const options = {
  modelId: 'COGNITE_3D_MODEL_ID',
  revisionId: 'COGNITE_3D_REVISION_ID',
};
viewer.addModel(options).then(model => {
  viewer.fitCameraToModel(model, 0);
});

// Load only geometries inside a bounding box, then focus camera on that area
const boundingBox = new THREE.Box3(
  new THREE.Vector3(0, 0, 0),
  new THREE.Vector3(10, 10, 10)
);

const options = {
  modelId: 'COGNITE_3D_MODEL_ID',
  revisionId: 'COGNITE_3D_REVISION_ID',
  geometryFilter: { boundingBox },
};

viewer.addModel(options).then(model => {
  // Transform the bounding box to model space
  boundingBox.applyMatrix4(model.matrix);
  // Focus camera on bounding box
  viewer.fitCameraToBoundingBox(boundingBox);
});

Returns Promise<Cognite3DModel>

addObject3D

Add a THREE.Object3D to the viewer

Parameters

• object THREE.Object3D -- A three.js object

Examples

const sphere = new THREE.Mesh(
  new THREE.SphereBufferGeometry(),
  new THREE.MeshBasicMaterial()
);
viewer.addObject3D(sphere);

removeObject3D

Remove a THREE.Object3D from the viewer

Parameters

• object THREE.Object3D -- A three.js object

Examples

const sphere = new THREE.Mesh(
  new THREE.SphereBufferGeometry(),
  new THREE.MeshBasicMaterial()
);
viewer.addObject3D(sphere);
viewer.removeObject3D(sphere);

setSlicingPlanes

Sets per-pixel slicing planes. Pixels behind any of the planes will be sliced away.

Parameters

• slicingPlanes THREE.Plane[] -- The planes to use for slicing

Examples

// Hide pixels with values less than 0 in the x direction
const plane = new THREE.Plane(new THREE.Vector3(1, 0, 0), 0);
viewer.setSlicingPlanes([plane]);

// Hide pixels with values greater than 20 in the x direction
const plane = new THREE.Plane(new THREE.Vector3(-1, 0, 0), 20);
viewer.setSlicingPlanes([plane]);

// Hide pixels with values less than 0 in the x direction or greater than 0 in the y direction
const xPlane = new THREE.Plane(new THREE.Vector3(1, 0, 0), 0);
const yPlane = new THREE.Plane(new THREE.Vector3(0, -1, 0), 0);
viewer.setSlicingPlanes([xPlane, yPlane]);

// Hide pixels behind an arbitrary, non axis-aligned plane
const plane = new THREE.Plane(new THREE.Vector3(1.5, 20, -19), 20);
viewer.setSlicingPlanes([plane]);

// Disable slicing planes
viewer.setSlicingPlanes([]);

getCameraPosition

Returns camera's position

Examples

const position = viewer.getCameraPosition();

Returns THREE.Vector3 Position in world space

getCameraTarget

Returns camera's target

Examples

const target = viewer.getCameraTarget();

Returns THREE.Vector3 Target in world space

setCameraPosition

Set camera's position

Parameters

• position THREE.Vector3 -- Position in world space

Examples

// store position, target
const position = viewer.getCameraPosition();
const target = viewer.getCameraTarget();
// restore position, target
viewer.setCameraPosition(position);
viewer.setCameraTarget(target);

setCameraTarget

Set camera's target

Parameters

• target THREE.Vector3 -- Target in world space

Examples

// store position, target
const position = viewer.getCameraPosition();
const target = viewer.getCameraTarget();
// restore position, target
viewer.setCameraPosition(position);
viewer.setCameraTarget(target);

fitCameraToBoundingBox

• See: getBoundingBox Move camera to a place where the content of a bounding box is visible to the camera.

Parameters

• box THREE.Box3 -- The bounding box in world space
• duration number? -- The duration of the animation moving the camera. Set this to 0 (zero) to disable animation.
• radiusFactor number? -- The ratio of the distance from camera to center of box and radius of the box (optional, default 4)

Examples

// Focus camera on bounding box over 500 milliseconds
viewer.fitCameraToBoundingBox(boundingBox, 500);

// Focus camera on bounding box instantaneously
viewer.fitCameraToBoundingBox(boundingBox, 0);

// Place the camera closer to the bounding box
viewer.fitCameraToBoundingBox(boundingBox, 500, 2);

// Animate camera to focus on a specific object with a given node id
const nodeId = 1234;
const boundingBox = model.getBoundingBox(nodeId);
viewer.fitCameraToBoundingBox(boundingBox, 1000);

disableKeyboardNavigation

• See: enableKeyboardNavigation

Disables camera navigation with the keyboard.

Examples

// Disable keyboard navigation on textbox focus
inputElement.addEventListener('focus', () => {
  viewer.disableKeyboardNavigation();
});

enableKeyboardNavigation

• See: disableKeyboardNavigation

Enables camera navigation with the keyboard.

Examples

// Enable keyboard navigation on textbox blur
inputElement.addEventListener('blur', () => {
  viewer.enableKeyboardNavigation();
});

fitCameraToModel

Move camera to a place where the 3D model is visible. It uses the bounding box of the 3D model and calls fitCameraToBoundingBox

Examples

// Fit camera to model
viewer.fitCameraToModel(model);

// Fit camera to model over 500 milliseconds
viewer.fitCameraToModel(model, 500);

// Fit camera to model instantaneously
viewer.fitCameraToModel(model, 0);

Parameters

• model Cognite3DModel -- The 3D model
• duration number? -- Same as for fitCameraToBoundingBox

worldToScreen

• See: https://www.w3schools.com/graphics/canvas_coordinates.asp

Convert a point in world space to its coordinates in the canvas. This can be used to place HTML objects near 3D objects on top of the 3D viewer.

Parameters

• point THREE.Vector3 -- World space coordinate.
• normalize bool? -- Optional. If true, coordinates are normalized into [0,1]. If false, the values are in the range [0, <canvas_size>). (optional, default false)

Examples

// Find canvas coordinates, i.e. where on the screen it is rendered, for an object with a given node id
const boundingBoxCenter = new THREE.Vector3();
// Find center of bounding box in world space
model.getBoundingBox(nodeId).getCenter(boundingBoxCenter);
// Screen coordinates of that point
const screenCoordinates = viewer.worldToScreen(boundingBoxCenter);

// Find normalized canvas coordinates, i.e. where on the screen it is rendered, for an object with a given node id
const boundingBoxCenter = new THREE.Vector3();
// Find center of bounding box in world space
model.getBoundingBox(nodeId).getCenter(boundingBoxCenter);
// Screen coordinates of that point normalized in the range [0,1]
const screenCoordinates = viewer.worldToScreen(boundingBoxCenter, true);

// Find canvas coordinates, i.e. where on the screen it is rendered, for an object with a given node id
const boundingBoxCenter = new THREE.Vector3();
// Find center of bounding box in world space
model.getBoundingBox(nodeId).getCenter(boundingBoxCenter);
// Screen coordinates of that point
const screenCoordinates = viewer.worldToScreen(boundingBoxCenter);
if (screenCoordinates == null) {
  // Object not visible on screen
} else {
  // Object is visible on screen
}

Returns (THREE.Vector2 | null) -- Returns 2D coordinates if the point is visible on screen, or null if object is outside screen.

getIntersectionFromPixel

Raycasting model(s) for finding where the ray intersects with the model.

Parameters

• x number -- X coordinate in pixels (relative to the domElement)
• y number -- Y coordinate in pixels (relative to the domElement)
• cognite3DModel Cognite3DModel? -- If specified then only give results for this model

Examples

const intersection = viewer.getIntersectionFromPixel(50, 100); // x = 50 pixels from the left, y = 100 pixels from the top
if (intersection)
  // it was a hit
  console.log(
    'You hit model ',
    intersection.model,
    ' at the node with id ',
    intersection.nodeId,
    ' at this exact point ',
    intersection.point
  );

Returns (Intersection | null) -- If there was an intersection then return the intersection object - otherwise it returns null if there was no intersections.

getScreenshot

Take screenshot from the current camera position.

Examples

// Add screenshot with resolution of the canvas to the page
const url = await viewer.getScreenshot();
const image = document.createElement('img');
image.src = url;
document.body.appendChild(url);

// Take screenshot with custom resolution
const url = await viewer.getScreenshot(1920, 1080);

Parameters

• width number? -- Width of the final image. Default is current canvas size.
• height number? -- Height of the final image. Default is current canvas size.

Returns Promise<string> A Blob URL to the image ('image/png')

Intersection

Type: object

Properties

• model Cognite3DModel -- The node id
• nodeId number -- The nodeId of the first intersected node
• point THREE.Vector3 -- The 3D position of the intersection point in the world coordinate system

Cognite3DModel

Extends THREE.Object3D

Cognite3DModel is the class representing a Cognite 3D model and its state

modelId

The id of the model in Cognite Data Fusion

revisionId

The id of the model revision in Cognite Data Fusion

getSubtreeNodeIds

Get all node ids in a subtree where the root node has id 'nodeId'

Parameters

• nodeId number -- The ID of the root node
• subtreeSize number? -- If you already know the subtreeSize, this will avoid an extra API call

Returns [number] List of nodeIds in the subtree

getBoundingBox

Get bounding box of a node

Parameters

• nodeId number -- The node's id
• box THREE.Box3? -- Optional target. Specify this to increase performance if the box can be reused.

Examples

const box = model.getBoundingBox(nodeId);

const reusableBox = new THREE.Box3();
const box = model.getBoundingBox(nodeId, reusableBox);
// box === reusableBox

Returns THREE.Box3

iterateNodes

Go through the node tree and apply an action to each node that has a node ID.

Examples

const url = await model.iterateNodes(console.log);

Parameters

• action Callback -- Callback function taking in a nodeId and treeId

Returns void

iterateSubtree

Go through the subtree a node of the tree and apply an action to each subtree node that has a node ID.

Examples

const url = await viewer.iterateSubtree(1111111111, console.log);

Parameters

• nodeId number -- The id of the node whose subtree will have action applied to
• action Callback -- Callback function taking in a nodeId and treeId
• treeIndex? number -- (Optional) The index within the tree for the given nodeId
• subtreeSize? number -- (Optional) The size of the subtree starting from nodeId

Returns Promise<boolean> Whether a valid nodeId was given or not

getNodeColor

• See: setNodeColor

Return the color on a node.

Parameters

• nodeId number -- The node's id

Returns {r: number, g: number, b: number} (r, g, b in the range [0, 255])

setNodeColor

• See: getNodeColor

Set the color on a node.

Parameters

• nodeId number -- The node's id
• r number -- The red color value (0-255)
• g number -- The green color value (0-255)
• b number -- The blue color value (0-255)

resetNodeColor

Reset a node's color to its original color.

Parameters

• nodeId number -- The node's id

selectNode

• See: deselectNode
• See: deselectAllNodes

Mark a node as selected. Only visible nodes can be selected.

Parameters

• nodeId number -- The node's id

deselectNode

• See: selectNode
• See: deselectAllNodes

Mark a node as deselected.

Parameters

• nodeId number -- The node's id

deselectAllNodes

Mark all selected nodes as deselected.

showNode

Show a node.

Parameters

• nodeId number -- The node's id

showAllNodes

Show all nodes.

hideAllNodes

Hide all nodes.

Parameters

• ghost bool -- Hide with ghost effect (optional, default false)

hideNode

Hide a node.

Parameters

• nodeId number -- The node's id
• ghost bool -- Hide with ghost effect (optional, default false)

Support

For support contact mailto:support@cognite.com