@cognite/3d-viewer

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.

Install
Cognite Data Fusion
Usage

- Sample code

- [Add progress listeners](#add-progress-listeners)
- [Make the model clickable](#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)...

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

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:

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: 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, <canvassize>). (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

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Readme

Table of Contents

Prerequisites

Install

Cognite Data Fusion

Usage

Requirements

Sample code

Add progress listeners

Make the viewer clickable

Load saved camera position from the API

API Reference

Table of Contents

Cognite3DViewer

Parameters

Examples

dispose

Examples

domElement

isBrowserSupported

Examples

on

Parameters

Examples

off

Parameters

Examples

addModel

Parameters

Examples

addObject3D

Parameters

Examples

removeObject3D

Parameters

Examples

setSlicingPlanes

Parameters

Examples

getCameraPosition

Examples

getCameraTarget

Examples

setCameraPosition

Parameters

Examples

setCameraTarget

Parameters

Examples

fitCameraToBoundingBox

Parameters

Examples

disableKeyboardNavigation

Examples

enableKeyboardNavigation

Examples

fitCameraToModel

Examples

Parameters

worldToScreen

Parameters

Examples

getIntersectionFromPixel

Parameters

Examples

getScreenshot

Examples

Parameters

Intersection

Properties

Cognite3DModel

modelId

revisionId

getSubtreeNodeIds

Parameters

getBoundingBox

Downloads in past