@cognite/3d-viewer

3D Viewer

This is the repository for the Cognite 3D Viewer. Currently this will also contain the documentation for the Cognite3DViewer.

3D Viewer Usage

For developers using the 3d-viewer, this will be the most important part of the documentation. Please follow the steps below to get development started

Setup

There are two ways of setting up the repo. If you have access to the currently internal npm repository, then you can include it as if a node_modules (import { Cognite3DViewer } from 'cognite-3d';). Otherwise, follow the below guide.

• The packaged viewer module will contain two files in the lib/ folder for usage, make sure you use lib/index.browser.js if you want to include this directly into your application, whether it is via html or js file.
  • <script> tag:

    <script src="./cognite-3d.bundle.js"></script> // Now you have 'cognite' as a global object
    ...
    <script>
    var viewer = new cognite.Cognite3DViewer({
      ...
    });
    // now you can use Viewer however you like!
    </script>
    

  • ES2015 modules:

    import { Cognite3DViewer } from './link/to/lib/cognite-3d.bundle.js';
    ...
    const viewer = new Cognite3DViewer({
      ...
    });
    

Api

Constructor

To create a Cognite3DViewer object, the constructor takes in an object, which can have the following options:

var viewer = new Cognite3DViewer({
  api: '0.4',               // required, currently 0.4
  project: string,          // required, this would be your tenant name, i.e. akso
  modelId: number,          // required, this would be your model id
  revisionId: number,       // required, this would be the revision id
  apiKey: APIKEEEYYY,       // required, the api key that is given to you, please don't leave it in the codebase!
  noBackground: boolean,    // optional. If the background should be transparent or not
  antialias: boolean,       // optional. Enable anitalias on rendering (avoid sharp edges). Will have negative performance impact on big 3D models.
  onClickListener: (nodeId, node) => {}, // optional, can be set later
  progressListener: function (step, totalSteps, subprogress, text){}, // optional, can be set later
});

After the viewer is constructed, it will have a canvas variable that is accessible. This would need to be appended into any DOM like below:

document.getElementById("app").appendChild(viewer.canvas);

Note: you may need additional styling to make the canvas fit the width, in the example above, the styling could be

#app {
  position: relative;
  width: 100vw;
  height: 400px;
}

#app > canvas {
  width: 100%;
  height: 100%;
}

After that is added, you should be good to go! use viewer.start() to begin rendering.

Additional Functions

The viewer object has plenty of additional api calls you can make, the below outlines some of these functionalities:

• viewer.start()
  • To start or resume the canvas and its listeners, you can use this after viewer.stop()
• viewer.stop()
  • To pause the canvas and its listeners, you can use this after viewer.start(). When paused, the viewer will no longer work in the background, allowing you to do other things, but the context is saved, allowing you to start with relatively no lag.
• viewer.toggleNodeSelected(nodeId)
  • To highlight a node, note that calling the same nodeId twice result it it being deselected.
• viewer.deselectAllNodes()
  • To clear all highlighted nodes
• viewer.getAssetFromNodeId(nodeId)
  • To get asset info on a node, which will give back a json with data field.
• viewer.setControlType("fpv|orbit|fpv-no-cursor")
  • To set a different control type, which is one of "fpv", "orbit" and "fpv-no-cursor"
  • To get asset info on a node, which will give back a json with data field.
• viewer.setOnClickListener((nodeId, node) => {})
  • Set a onClick listener, or override a old onClick listener for nodes.
  • To get asset info on a node, which will give back a json with data field.
• viewer.setColorOnNode(nodeId, color, alpha)
  • Set a color on the given nodeId

Development Usage

Build

You will need yarn (npm install -g yarn). Run yarn to install packages. Run yarn run start to run.

Building the library

• run npm publish, make sure you have bumped the version first!
• NOTE: if it does not work, it is because you are probably not connected to bastion or you dont have the .npmrc or .yarnrc setup properly. See Link for more details on Private npm repository section.

How does this work?

Look at src/main.js for more info Link