Skip to main content
Version: 3.x

Installation

The library has a peer-dependency on Cognite Data Fusion JS-SDK which must be installed as a dependency in the client application that uses Reveal.

npm install @cognite/reveal @cognite/sdk

If you will be using ThreeJS directly from the application, you will also need to install the correct version of ThreeJS and types information if you are using TypeScript:

npm install three@<version>
npm install --save-dev @types/three@<version>

Please find the correct version of ThreeJS in the release documentation on Github.

Regarding WebWorkers​

Reveal uses Web Workers and WebAssembly to handle 3D geometry. This causes some problems when bundling and loading packages from NPM. Some effort might therefore be needed before Reveal can be used in your project depending on how the servers hosting your application are configured.

There are two different types of deployment scenarios:

  1. Projects where Cognite CDN apps-cdn.cognitedata.com is available (no restrictive Content-Security-Policy-headers are set, or apps-cdn is whitelisted)

  2. Projects with CSP that forbids to fetch scripts from apps-cdn.cognitedata.com.

By default, Reveal will try to fetch its worker/WASM files from apps-cdn.cognitedata.com. If there are no CSP in your project that forbids that, Reveal should work out of the box without any additional steps.

In case if you see an error like the following in your development console:

Refused to load the script 'https://apps-cdn.cognitedata.com/@cognite/reveal-parser-worker@1.1.0/reveal.parser.worker.js' because it violates the following Content Security Policy directive: "script-src 'self' https://localhost:* blob:"

See the steps below.

Installation for projects with Content-Security-Policy​

What you'll need to do is to host worker/wasm files at some server from which your browser can download and run js code.

Before going with any of the steps below, consider to just whitelist Cognite CDN in your Content-Security-Policy. All you need to do is to add into your CSP:

  • script-src apps-cdn.cognitedata.com
  • worker-src blob: (only the first option described below doesn't need worker-src blob:)

Also, notice that because Safari browser doesn't support WebAssembly.InstantiateStreaming yet, so it uses WebAssembly.instantiate which requires script-src: unsafe-eval to be presented in CSP. Evaluate security risks before adding unsafe-eval to your CSP.

If whitelisting of apps-cdn.cognitedata.com is not an options for you, go with one of the steps below.

Option 1: include Web Worker and WebAssembly files as static assets in your project​

Copy all files from /node_modules/@cognite/reveal-parser-worker/dist/local to some static folder in your project. E.g., for React projects, the typical folder is /public.

You can add this command to your build scripts:

cp ./node_modules/@cognite/reveal-parser-worker/dist/local/* ./public/reveal-worker

The point is that parser-worker files should be available under some network path like in that case https://localhost:xxxx/reveal-worker/reveal.parser.worker.js if you can see script content in your browser you're almost done.

The only thing left is to tell the reveal library from which path workers should be fetched. To do that, use revealEnv:

import { revealEnv, Cognite3DViewer } from '@cognite/reveal';
revealEnv.publicPath = `/reveal-worker/`;

// ... then use reveal normally ...
const viewer = new Cognite3DViewer(/*...*/)
Other copying options

Below are few more convenient options for copying if you don't like having that command in your package.json:

  cp ./node_modules/@cognite/reveal-parser-worker/dist/local/* ./public/reveal-worker

Option 1.1: Copy worker files locally in a create-react-app based project​

  1. Install react-app-rewired. It's required to slightly modify react-scripts from create-react-app without running eject

    npm install react-app-rewired --save-dev

  2. 'Flip' the existing calls to react-scripts in npm scripts for start, build and test

    /package.json
      "scripts": {
    -   "start": "react-scripts start",
    +   "start": "react-app-rewired start",
    -   "build": "react-scripts build",
    +   "build": "react-app-rewired build",
    -   "test": "react-scripts test",
    +   "test": "react-app-rewired test",
        "eject": "react-scripts eject"
    }

  3. Install copy-webpack-plugin

     npm install copy-webpack-plugin --save-dev

  4. Create a config-overrides.js file in the root directory with the following content

    ./config-overrides.js
    const CopyWebpackPlugin = require('copy-webpack-plugin');

    const revealSource = 'node_modules/@cognite/reveal';

    module.exports = function override(config) {
      if (!config.plugins) {
        // eslint-disable-next-line no-param-reassign
        config.plugins = [];
      }

      // that's for 6.x version of webpack-copy-plugin
      // if you use 5.x just put content of patterns into constructor
      // new CopyWebpackPlugin([ /* { from, to } */ ])
      config.plugins.push(
        new CopyWebpackPlugin({
          patterns: [
            {
              from: `${revealSource}/**/*.worker.js`,
              to: '.',
              flatten: true,
            },
            {
              from: `${revealSource}/**/*.wasm`,
              to: '.',
              flatten: true,
            },
          ],
        })
      );

      return config;
    };

Now all *.worker.js and *.wasm files from @cognite/reveal should be copied into your output folder when you run build.

Option 1.2: Copy worker files locally for non-create-react-app based projects​

Just make sure that you have *.worker.js and *.wasm files from @cognite/reveal in your output folder.

If you use webpack, you might want to add copy-webpack-plugin@^5.1.1 in your webpack.config.js

// webpack.config.js
const revealSource = 'node_modules/@cognite/reveal';

{
  /* ... */
  plugins: [
    new CopyWebpackPlugin({
      patterns: [
        {
          from: `${revealSource}/**/*.worker.js`,
          to: '.',
          flatten: true,
        },
        {
          from: `${revealSource}/**/*.wasm`,
          to: '.',
          flatten: true,
        },
      ],
    })
  ]
}

Option 2: host Web Worker and WebAssembly files externally​

In case if there is no such /public or similar folder in your project, you're likely using a different service to host static assets. The domain of that service is probably whitelisted in Content Security Policy and can be used to host the necessary files.

In that case, the only thing you can do is to build the reveal-parser-worker from sources with correct publicPath.

Let's say your static server has that URL https://static.server/ and you can upload the files at some folder, e.g. parser-worker folder. So files should be available at https://static.server/parser-worker/

Then all you need to do is:

  1. Clone or download @cognite/reveal.
  2. cd ./reveal/parser-worker
  3. Consult parser-worker/README.md and install the necessary build tools
  4. You will need to set PUBLIC_PATH env variable that points at your static server. Run the build with that env variable. You will see the publicPath printed to console during the build.
PUBLIC_PATH="https://static.server/parser-worker/" yarn build:prod

If you set the environment variable correctly, you should see it printed to console during the build:

> ⬡ <webpack-log>: Worker local build config:
> ⬡ <webpack-log>:  { publicPath: 'https://static.server/parser-worker/' }

  1. Take the files from ./parser-worker/dist/local and host them on your CDN at the path you specified – https://static.server/parser-worker/.

  2. In your project, specify revealEnv.publicPath

import { revealEnv, Cognite3DViewer } from '@cognite/reveal';
revealEnv.publicPath = `https://static.server/parser-worker/`;

// ... then use reveal normally ...
const viewer = new Cognite3DViewer(/*...*/)

Everything should work fine now.

A note on Content-type header for .wasm files​

important

Make sure your server sends *.wasm files with Content-type: application/wasm header.

Sometimes servers don't have correct MIME type set for wasm files. In that case you might notice this message in a browser console when it fetches a .wasm file:

Uncaught (in promise) TypeError: Failed to execute 'compile' on 'WebAssembly': Incorrect response MIME type. Expected 'application/wasm'.

In that case you'll need to configure your server to set the Content-type: application/wasm header for *.wasm files. If you use the nginx add types in the config or edit the mime.types file.

/mime.types
types {
    application/wasm wasm;
}