@cognite/3d-viewer
Advanced tools
Visualize Cognite's 3D models in a web browser with WebGL.
You need to install the Cognite SDK which needs to be authenticated before loading the 3D viewer.
$ npm install @cognite/3d-viewer
To be able to use this 3D viewer you need to have access to Cognite's Data Platform (CDP). You can upload 3D models to our platform by looking at Cognite's API documentation. You can then use this viewer to visualize the 3D model in any web-based application.
import { Cognite3DViewer } from '@cognite/3d-viewer';
// Remember to authenticate with the Cognite SDK.
const viewer = new Cognite3DViewer();
To be able to use this package you need the following polyfills:
// Remember to authenticate with the Cognite SDK.
const viewer = new Cognite3DViewer();
// The viewer will render to a canvas.
// Add this canvas to your DOM
document.body.appendChild(viewer.getCanvas());
// At this point you will only see a black canvas.
// So let's add a 3D model:
const options = {
projectName, // Project name (tenant) in Cognite's Data Platform
modelId, // 3D model id (has to be under the same project)
revisionId, // The model's revision id
};
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 canvas to make it fit your use-case. By default the canvas will have this style:
{ width: 100%; height: 100%; }
function onProgress(progress) {
console.log(progress);
}
function onComplete() {
console.log('Model loaded');
}
const options = {
projectName,
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, null, model.matrix);
viewer.fitCameraToBoundingBox(boundingBox, 2000); // 2 sec
} else {
// Clicked outside the 3D model
}
});
Assume you have the revision object from Cognite's Data Platform 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);
}
Cognite3DViewer is the root class of a Cognite 3D viewer. It controls all aspects of the 3D viewer.
options Object (optional, default {})
options.noBackground boolean -- Transparent background or not (optional, default false)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'.const viewer = new Cognite3DViewer({
noBackground: true,
});
Returns the canvas the viewer is rendered on
document.body.appendChild(viewer.getCanvas());
Check if the viewer supports the current browser
if (!viewer.isSupported()) {
// create an error message to the user?
}
Add event listener to the viewer call off to remove an event listener
type string -- Event type ('click' or 'cameraChange')func function (event:PointerEvent) -- The callback functionconst onClick = event => { ... };
viewer.on('click', onClick);
viewer.on('cameraChange', (position, target) => {
console.log('Camera changed: ', position, target);
});
Remove event listener from the viewer call on to add an event listener
type string -- Event type ('click' or 'cameraChange')func function -- The callback function used in onviewer.off('click', onClick);
Add a new 3D model to the viewer. call fitCameraToModel to see the model after the model has loaded
options Object
options.projectName string -- The Cognite project the 3D model belongs tooptions.modelId number -- The model's idoptions.revisionId number -- The model's revision idoptions.boundingBox THREE.Box3? -- Only load geometries inside this bounding boxoptions.onProgress function (progress: Object)? -- Callback for progress eventsoptions.onComplete function? -- Callback when the model is fully loadedconst options = {
projectName: 'COGNITE_TENANT_NAME',
modelId: 'COGNITE_3D_MODEL_ID',
revisionId: 'COGNITE_3D_REVISION_ID',
};
viewer.addModel(options).then(model => {
viewer.fitCameraToModel(model, 0);
});
Returns Promise<Cognite3DModel>
Add a THREE.Object3D to the viewer
object THREE.Object3D -- A three.js objectconst sphere = new THREE.Mesh(new THREE.SphereBufferGeometry(), new MeshBasicMaterial());
viewer.addObject3D(sphere);
Remove a THREE.Object3D from the viewer
object THREE.Object3D -- A three.js objectconst sphere = new THREE.Mesh(new THREE.SphereBufferGeometry(), new MeshBasicMaterial());
viewer.addObject3D(sphere);
viewer.removeObject3D(sphere);
Set slice point. Geometries will be hidden relative to this point based on slice planes specified by setSlicePlanes.
slicePoint THREE.Vector3 -- Slice pointconst slicePoint = new THREE.Vector3(1, 0, 0);
viewer.setSlicePoint(slicePoint);
Set slice planes. Each component controls slicing for its direction. A value of +1 hides geometries in the positive direction relative to slicePoint. A value of -1 hides geometries in the negative direction relative to slicePoint. A value of 0 disables slicing for that plane.
slicePlanes THREE.Vector3 -- Slice plane information// Hide geometries with larger z-component than slicePoint. No slicing in x and y.
const slicePlanes = new THREE.Vector3(0, 0, 1);
viewer.setSlicePlanes(slicePlanes);
// Hide geometries with smaller x-component than slicePoint.
const slicePlanes = new THREE.Vector3(-1, 0, 0);
viewer.setSlicePlanes(slicePlanes);
// Hide geometries with larger x,y and z-component than slicePoint.
const slicePlanes = new THREE.Vector3(1, 1, 1);
viewer.setSlicePlanes(slicePlanes);
// Disable slicing.
const slicePlanes = new THREE.Vector3(0, 0, 0);
viewer.setSlicePlanes(slicePlanes);
Returns camera's position
const position = viewer.getCameraPosition();
Returns THREE.Vector3 Position in world space
Returns camera's target
const target = viewer.getCameraTarget();
Returns THREE.Vector3 Target in world space
Set camera's position
position THREE.Vector3 -- Position in world space// store position, target
const position = viewer.getCameraPosition();
const target = viewer.getCameraTarget();
// restore position, target
viewer.setCameraPosition(position);
viewer.setCameraTarget(target);
Set camera's target
target THREE.Vector3 -- Target in world space// store position, target
const position = viewer.getCameraPosition();
const target = viewer.getCameraTarget();
// restore position, target
viewer.setCameraPosition(position);
viewer.setCameraTarget(target);
Move camera to a place where the content of a bounding box is visible to the camera.
box THREE.Box3 -- The bounding box in world spaceduration number? -- The duration of the animation moving the camera. Set this to 0 (zero) to disable animation.radiusFactor number? -- The the ratio of the distance from camera to center of box and radius of the box (optional, default 4)Enables camera navigation with the keyboard.
Disables camera navigation with the keyboard.
Move camera to a place where the 3D model is visible. It uses the bounding box of the 3D model and calls fitCameraToBoundingBox
model Cognite3DModel -- The 3D modelduration number? -- Same as for fitCameraToBoundingBoxConvert 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.
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)const boundingBoxCenter = new THREE.Vector3();
// Find center of bounding box in world space
model.getBoundingBox(nodeId, null, model.matrix).getCenter(boundingBoxCenter);
// Screen coordinates of that point
const screenCoordinates = viewer.worldToScreen(boundingBoxCenter);
const boundingBoxCenter = new THREE.Vector3();
// Find center of bounding box in world space
model.getBoundingBox(nodeId, null, model.matrix).getCenter(boundingBoxCenter);
// Screen coordinates of that point normalized in the range [0,1]
const screenCoordinates = viewer.worldToScreen(boundingBoxCenter, true);
const boundingBoxCenter = new THREE.Vector3();
// Find center of bounding box in world space
model.getBoundingBox(nodeId, null, model.matrix).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.
Raycasting model(s) for finding where the ray intersects with the model.
x number -- X coordinate in pixels (relative to the canvas)y number -- Y coordinate in pixels (relative to the canvas)cognite3DModel Cognite3DModel? -- If specified then only give results for this modelconst 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.
Take screenshot from the current camera position.
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')
Type: object
model Cognite3DModel -- The node idnodeId number -- The nodeId of the first intersected nodepoint THREE.Vector3 -- The 3D position of the intersection point in the world coordinate systemExtends THREE.Object3D
Cognite3DModel is the class represeting a Cognite 3D model and its state
Get all node ids in a subtree where the root node has id 'nodeId'
nodeId number -- The ID of the root nodesubtreeSize number? -- If you already know the subtreeSize then this can help avoid an API callReturns [number] List of nodeIds in the subtree
Get bounding box of a node
nodeId number -- The node's idbox THREE.Box3? -- Optional target. Specify this to increase performance if the box can be reused.matrix THREE.Matrix4? -- Optional transformation matrix. If not specified, identity matrix is used and bounding box will be in local space of the model.const box = model.getBoundingBox(nodeId);
const reusableBox = new THREE.Box3();
const box = model.getBoundingBox(nodeId, reusableBox, model.matrix); // world space
// box === reusableBox
model.updateMatrixWorld();
const reusableBox = new THREE.Box3();
const matrix = model.matrixWorld;
const box = model.getBoundingBox(nodeId, reusableBox, matrix);
// box === reusableBox
Returns THREE.Box3
Return the color on a node
nodeId number -- The node's idReturns {r: number, g: number, b: number}
Set the color on a node
nodeId number -- The node's idr number -- The red color value (0-255)g number -- The green color value (0-255)b number -- The blue color value (0-255)Reset a node's color to its original color
nodeId number -- The node's idMark a node as selected. Only visible nodes can be selected.
nodeId number -- The node's idMark a node as deselected.
nodeId number -- The node's idMark all selected nodes as deselected
Show a node
nodeId number -- The node's idShow all nodes
Hide all nodes
ghost bool -- Hide with ghost effect (optional, default false)Hide a node
nodeId number -- The node's idghost bool -- Hide with ghost effect (optional, default false)Cognite3DModelLoader is the class used to load a Cognite 3D model to Three.js.
options Object? (optional, default {})
options.projectName string -- The Cognite project the 3D model belongs tooptions.modelId number -- The model's idoptions.revisionId number -- The model's revision idoptions.boundingBox THREE.Box3? -- Only load geometries inside this bounding boxoptions.onProgress function (progress: Object)? -- Callback for progress eventsoptions.onComplete function? -- Callback when the model is fully loadedconst options = {
projectName: 'COGNITE_TENANT_NAME',
modelId: 'COGNITE_3D_MODEL_ID',
revisionId: 'COGNITE_3D_REVISION_ID',
};
Cognite3DModelLoader.load(options).then(model => {
// if we have a THREE.Scene then:
scene.add(model);
});
Returns Promise<Cognite3DModel>
For support contact mailto:support-3d@cognite.com
FAQs
JavaScript viewer to visualize 3D models on Cognite Data Fusion
The npm package @cognite/3d-viewer receives a total of 109 weekly downloads. As such, @cognite/3d-viewer popularity was classified as not popular.
We found that @cognite/3d-viewer demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 176 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
Security News
React's CRA deprecation announcement sparked community criticism over framework recommendations, leading to quick updates acknowledging build tools like Vite as valid alternatives.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.