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
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:
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
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, defaultfalse
) -
options.logMetrics
boolean -- Send anonymous usage statistics. (optional, defaulttrue
) -
options.highlightColor
boolean -- Highlight color of the selected objects (optional, defaultTHREE.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
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, default4
)
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
Disables camera navigation with the keyboard.
Examples
// Disable keyboard navigation on textbox focus
inputElement.addEventListener('focus', () => {
viewer.disableKeyboardNavigation();
});
enableKeyboardNavigation
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
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, defaultfalse
)
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, defaultfalse
)
hideNode
Hide a node.
Parameters
-
nodeId
number -- The node's id -
ghost
bool -- Hide with ghost effect (optional, defaultfalse
)
Support
For support contact mailto:support@cognite.com