@cognite/3d-viewer
Advanced tools
Visualize Cognite's 3D models in a web browser with WebGL.
$ 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';
const viewer = new Cognite3DViewer();
<script src="{path to this folder}/lib/cognite.bundle.js"></script> // Now you have 'cognite' as a global object
<script>
var viewer = new cognite.Cognite3DViewer();
</script>
const viewer = new Cognite3DViewer();
// The viewer will render to a canvas.
// Add this canvas to your DOM
document.body.appendChild(viewer.canvas);
// start rendering
viewer.start();
// 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
canvas { 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 nodeId = model.getNodeIdFromPixel(viewer.camera, viewer.renderer, offsetX, offsetY);
if (nodeId != null) {
// 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
}
});
Cognite3DViewer is the root class of a Cognite 3D viewer. It controls all aspects of the 3D viewer.
options Object (optional, default {})
const viewer = new Cognite3DViewer({
noBackground: true,
});
Check if the viewer supports the current browser
if (!viewer.isSupported()) {
// create an error message to the user?
}
Start viewer, or resume after calling stop().
viewer.start();
Stop the viewer. When stopped, the viewer will not do work, but it's state will be kept so it can restart immediately after start() is called.
viewer.stop();
Add event listener to the viewer call off to remove an event listener
type "click"func function (event:MouseEvent) -- The callback functionconst onClick = event => { ... };
viewer.on('click', onClick);
Remove event listener from the viewer call on to add an event listener
viewer.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.sectors [number]? -- List of sector ID's to loadoptions.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>
Returns camera's position
const position = viewer.getCameraPosition();
Returns THREE.Vector3 Position in global space
Returns camera's target
const target = viewer.getCameraTarget();
Returns THREE.Vector3 Target in global space
Set camera's position
position THREE.Vector3 -- Position in global 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 global 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 boxduration 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 fitCameraToBoundingBoxTake 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')
Extends THREE.Object3D
Cognite3DModel is the class represeting a Cognite 3D model and it's 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 a 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.const box = model.getBoundingBox(nodeId);
const reusableBox = new THREE.Box3();
const box = model.getBoundingBox(nodeId, reusableBox);
// box === reusableBox
Returns THREE.Box3
Raycasting for nodes
camera THREE.Camera -- The camera to project fromrenderer THREE.WebGLRenderer -- A renderer. The raycaster will render an image to memory for efficiency.x number -- X coordinate in pixelsy number -- Y coordinate in pixelsconst box = model.getBoundingBox(nodeId);
const reusableBox = new THREE.Box3();
const box = model.getBoundingBox(nodeId, reusableBox);
// box === reusableBox
Returns (number | null) -- If there was a hit then returns the node id
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)Mark a node as 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
makeGray bool -- Hide by coloring gray (optional, default false)Hide a node
nodeId number -- The node's idmakeGray bool -- Hide by coloring gray (optional, default false)Get a single node.
projectName string -- The Cognite project that the 3D model belongs tomodelId number -- The ID of the 3D modelrevisionId number -- The ID of the 3D model revisionnodeId number -- The ID of the node to retrieve.Type: object
id number -- The node idtreeIndex number -- The tree indexparentId number -- The node id of the parentname number -- The name of the nodesubtreeSize number -- Size of the subtree where this node is the root. This number included the node it self.depth number -- The depth level from the overall root node (0-indexed).boundingBox THREE.Box3 -- The bounding box for the subtree where this node is the root.Get the assets associated with a given node.
projectName string -- The Cognite project that the 3D model belongs tomodelId number -- The ID of the 3D modelrevisionId number -- The ID of the 3D model revisionnodeId number -- The ID of the node to get the associated assets ofReturns Promise<[AssetMapping]>
Type: object
nodeId number -- The node id for the mappingassetId number -- The mapped asset idsubtreeSize number -- Size of the subtree with the node with id = nodeId as rootGet the node ids associated with a given asset.
projectName string -- The Cognite project that the 3D model belongs tomodelId number -- The ID of the 3D modelrevisionId number -- The ID of the 3D model revisionassetId number -- The ID of the asset to get the associated nodes ofReturns Promise<[AssetMapping]>
Type: object
id number -- The sector idparentId number? -- The id of the parent sector. Undefined if it is the root sector.path number -- A string representing the path from the root sector to this sector. Describes how to traverse a octree to get to this sector.depth number -- The depth level from the root sector (0-indexed).threedFileId number -- File id for the file describing geometries attached to the sector. Use /3d/files to retrieve it.boundingBox THREE.Box3 -- The bounding box of which the sector covers.Get sectors intesecting a bounding box.
projectName string -- The Cognite project that the 3D model belongs tomodelId number -- The ID of the 3D modelrevisionId number -- The ID of the 3D model revisionboundingBox THREE.Box3 -- The bounding boxReturns Promise<[Sector]> A list of sectors intersecting the bounding box
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.sectors [number]? -- List of sector ID's to loadoptions.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 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 36 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
Research
The Socket Research Team uncovered a malicious Python package typosquatting the popular 'fabric' SSH library, silently exfiltrating AWS credentials from unsuspecting developers.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.