4.20.1 • Published 9 months ago

@cognite/reveal v4.20.1

Weekly downloads
476
License
Apache-2.0
Repository
github
Last release
9 months ago

Reveal viewer

Documentation for the latest version is available at https://cognitedata.github.io/reveal-docs/docs. Documentation for the next release is available from https://cognitedata.github.io/reveal-docs/docs/next/.

The documentation has a bunch of live examples.

Code Example

import { Cognite3DViewer } from "@cognite/reveal";
import { CogniteClient, CogniteAuthentication } from "@cognite/sdk";

const appId = "com.cognite.reveal.example";
const client = new CogniteClient({
  appId,
  project,
  getToken
});

async function start() {
  await client.authenticate();

  const viewer = new Cognite3DViewer({
    sdk: client,
    domElement: document.querySelector("#your-element-for-viewer")
  });
  viewer.addModel({ modelId: 4715379429968321, revisionId: 5688854005909501 });
}

const project = "publicdata";
const legacyInstance = new CogniteAuthentication({
  project,
});

const getToken = async () => {
  await legacyInstance.handleLoginRedirect();
  let token = await legacyInstance.getCDFToken();
  if (token) {
    return token.accessToken;
  }
  token = await legacyInstance.login({ onAuthenticate: "REDIRECT" });
  if (token) {
    return token.accessToken;
  }
  throw new Error("authentication error");
};

start();

Installation

npm install @cognite/reveal @cognite/sdk three@<version>

Please find the correct version of ThreeJS in the release documentation on Github. We only guarantee support for the exact ThreeJS version specified there.

See our documentation for usage.

Prerequisites

For development, you will need to install Node, Yarn and Rust+Cargo.

Run yarn in the viewer

Local Packages

The Reveal viewer is structured using local packages. This allows you to test features in isolation and constrain the dependencies with logical barriers between features. Packages are located in the /packages/ subfolder. There is no enforced structure of the packages and their layout and content will vary depending on what the package exposes to the rest of the system. Dependencies that are located in the viewer/package.json will be shared and are accessible by any package without having to explicitly declare a dependency in the respective package's package.json. Any external dependency (e.g. lodash, threejs, etc.) must be declared in the root package.json such that they will be properly installed by users that consume the Reveal NPM package.

Creating a local package

Create a new folder under the /packages/ folder, e.g. /packages/[MY-PACKAGE-NAME] and include a package with the following structure:

{
  "name": "@reveal/[MY-PACKAGE-NAME]",
  "private": true,
  "main": "index.ts",
}

Technically the private: true field can be omitted but it is highly recommended such that one does not accidentally publish the local package to NPM with the npm publish command. The index.ts should include any types, functions and/or classes you wish to expose to consumers of this package. You should also create a README.md file for your package that explains its intent and any information that is needed to use the package.

If your package depends on another local package, it must be explicitly declared as a dependency:

{
  "name": "@reveal/[MY-PACKAGE-NAME]",
  "private": true,
  "main": "index.ts",
  "dependencies": {
    "@reveal/[SOME-LOCAL-PACKAGE]": "workspace:*"
  }
}

The workspace keyword declares that the dependency is a local package and should never be fetched from NPM. And the ':*' syntax means that it should just grab any version available. See this for more documentation on yarn workspaces.

If you want to add Rust/Webassembly code to a package, you can add the following script in package.json:

{
  "scripts": {
    "run-wasm-pack": "yarn run ws:update-cargo-index && wasm-pack"
  }
}

and let the Cargo crate reside in <package-name>/wasm. Then the crate will automatically be built and tested by the build and test scripts in the workspace root respectively. The ws:update-cargo-index step ensures that the local crates.io index has been updated before running build. Otherwise, the index update will be executed in a quiet manner, and the command may appear to hang for several minutes.

When writing tests in Rust, the tests must be annotated with the #[wasm_bindgen_test] attribute, instead of the conventional #[test], and wasm-bindgen-test must be added as a (dev-)dependency. All tests are run as part of the normal yarn test script in the root folder, but can also be run manually with e.g. wasm-pack test --chrome --headless in the relevant wasm folder.

It is also possible to run and test a local package in isolation from the rest of Reveal. Convenience functionality has been created to make this easy. Add the following script to your package's package.json:

{
  "scripts": {
    "test": "yarn ws:test --config ./../../jest.config.js"
  }
}

Running yarn run test will run all tests in your package that resolves the *.test.* regex pattern.

To run a test app that includes your package (and any dependencies), create a /app/ subfolder in your package that includes an index.ts file. Add the following script to your package's package.json:

{
  "scripts": {
    "start": "yarn ws:start"
  }
}

Running the command yarn start will host a localhost site with a template HTML that includes the /app/index.ts script that has been transpiled to javascript. To see an example of this check out the packages/camera-manager package.

API Extractor

The viewer/reveal.api.md file contains a description of the public API of Reveal. In the CI pipeline, the reveal.api.md file is checked to be up-to-date by API extractor.

In order to update this file locally, run yarn run update-api after having run the build script. This will update the API file with any changes, which should be added and committed in the same PR.

Debugging

Worker source maps

When bundling source maps with inlined web workers, the bundle size grows huge. Therefore source maps for workers are disabled by default. In order to add source maps to workers, pass --env workerSourceMaps=true to the yarn build script.

Creating and running visual tests

Visual test files must be on the format visual-tests/SomeTest.VisualTest.ts. See one of the existing tests for example on how to create a test.

Visual tests can be run from viewer/ using yarn test:visual. This will run all visual tests. You can also run a single test by using yarn test:visual -- -t="SomeTest" (will run all tests with "SomeTest" in the name). Note that arguments only will be passed to the client, to pass arguments to the server you will need to manually start the server and client separately.

For more information about visual tests, see visual-tests/README.md.

Recommended package folder structure

├── app                   # Runnable app
│ └──index.ts             # Entry point for runnable app
├── src                   # Source code for package
├── wasm                  # Rust/Webassembly source code for package
├── test                  # Automated tests
├── package.json          # Package declaration
├── index.ts              # Entry point for package
└── README.md             # Readme
4.20.0

9 months ago

4.20.1

9 months ago

4.19.1

9 months ago

4.19.0-dev.20241021

10 months ago

4.18.0-dev.20241017

10 months ago

4.19.0-dev.20241018

10 months ago

4.19.0

10 months ago

4.18.0-dev.20241016

10 months ago

4.18.0

10 months ago

4.17.1-dev.20241015

10 months ago

4.17.1-dev.20240927

10 months ago

4.17.1-dev.20240926

10 months ago

4.17.1-dev.20240930

10 months ago

4.17.1-dev.20241010

10 months ago

4.17.1-dev.20241011

10 months ago

4.17.1-dev.20241014

10 months ago

4.17.1-dev.20241007

10 months ago

4.17.1-dev.20241009

10 months ago

4.17.1-dev.20241008

10 months ago

4.17.1-dev.20241001

10 months ago

4.17.1-dev.20241003

10 months ago

4.17.1-dev.20241002

10 months ago

4.17.1-dev.20241004

10 months ago

4.17.1-dev.20240925

10 months ago

4.17.1-dev.20240924

10 months ago

4.16.1-dev.20240829

11 months ago

4.16.1-dev.20240828

11 months ago

4.16.1-dev.20240827

11 months ago

4.16.1-dev.20240826

11 months ago

4.17.0-dev.20240830

11 months ago

4.17.1-dev.20240905

11 months ago

4.17.1-dev.20240904

11 months ago

4.17.1-dev.20240906

11 months ago

4.17.1-dev.20240909

11 months ago

4.17.1-dev.20240903

11 months ago

4.17.1-dev.20240920

11 months ago

4.17.1-dev.20240923

10 months ago

4.17.1-dev.20240916

11 months ago

4.17.1-dev.20240918

11 months ago

4.17.1-dev.20240917

11 months ago

4.17.1-dev.20240919

11 months ago

4.17.1-dev.20240910

11 months ago

4.17.1-dev.20240912

11 months ago

4.17.1-dev.20240911

11 months ago

4.17.1-dev.20240913

11 months ago

4.17.0-dev.20240902

11 months ago

4.17.0

11 months ago

4.17.1

11 months ago

4.16.1-dev.20240821

12 months ago

4.14.5

1 year ago

4.16.1-dev.20240820

12 months ago

4.14.6

1 year ago

4.14.7

1 year ago

4.14.8

1 year ago

4.16.1-dev.20240823

11 months ago

4.16.1-dev.20240822

12 months ago

4.14.4

1 year ago

4.14.9

1 year ago

4.16.1-dev.20240807

12 months ago

4.16.1-dev.20240806

12 months ago

4.16.1-dev.20240805

12 months ago

4.16.1-dev.20240809

12 months ago

4.16.1-dev.20240808

12 months ago

4.16.1-dev.20240814

12 months ago

4.16.1-dev.20240813

12 months ago

4.16.1-dev.20240812

12 months ago

4.16.1-dev.20240816

12 months ago

4.16.1-dev.20240815

12 months ago

4.16.1-dev.20240819

12 months ago

4.16.0

1 year ago

4.16.1

1 year ago

4.15.0

1 year ago

4.15.1

1 year ago

4.15.2

1 year ago

4.14.2

1 year ago

4.14.3

1 year ago

4.14.1

1 year ago

4.14.0

1 year ago

4.13.0

1 year ago

4.12.1

1 year ago

4.12.0

1 year ago

4.11.1

1 year ago

4.11.0

1 year ago

4.10.8

1 year ago

4.10.7

1 year ago

4.10.6

1 year ago

4.10.5

1 year ago

4.10.4

1 year ago

4.10.3

1 year ago

4.10.2

1 year ago

4.10.1

1 year ago

4.10.0

1 year ago

4.9.2

1 year ago

4.9.1

1 year ago

4.9.0

2 years ago

4.8.0

2 years ago

4.7.1

2 years ago

4.7.0

2 years ago

4.6.0

2 years ago

4.5.0

2 years ago

4.5.1

2 years ago

4.4.1

2 years ago

4.4.0

2 years ago

4.4.3

2 years ago

4.4.2

2 years ago

4.3.4

2 years ago

4.3.2

2 years ago

4.3.3

2 years ago

4.3.1

2 years ago

4.3.0

2 years ago

4.2.2

2 years ago

4.2.1

2 years ago

4.2.0

2 years ago

4.1.2

2 years ago

4.1.0

3 years ago

4.1.1

3 years ago

3.2.1

3 years ago

4.0.0

3 years ago

3.3.0

3 years ago

3.2.0

3 years ago

3.1.0

3 years ago

3.0.2

3 years ago

3.0.1

3 years ago

3.0.0

3 years ago

3.0.0-alpha.1

4 years ago

3.0.0-alpha.0

4 years ago

3.0.0-alpha.2

4 years ago

3.0.0-beta.1

3 years ago

3.0.0-beta.0

3 years ago

2.3.0

3 years ago

2.2.1

4 years ago

2.2.0

4 years ago

2.2.2

4 years ago

2.1.2

4 years ago

2.1.1

4 years ago

2.1.0

4 years ago

2.0.0

4 years ago

2.0.0-beta.4

4 years ago

2.0.0-beta.2

4 years ago

2.0.0-beta.3

4 years ago

2.0.0-beta.1

4 years ago

2.0.0-beta.0

4 years ago

1.5.5

4 years ago

1.5.4

4 years ago

1.5.3

4 years ago

1.5.2

4 years ago

1.5.1

4 years ago

1.5.0

4 years ago

1.4.0

4 years ago

1.3.1

5 years ago

1.3.0

5 years ago

1.2.3

5 years ago

1.2.2

5 years ago

1.2.1

5 years ago

1.2.0

5 years ago

1.1.0

5 years ago

1.0.0

5 years ago

1.0.0-beta-3

5 years ago

1.0.0-beta-2

5 years ago

1.0.0-beta-1

5 years ago

1.0.0-alpha-5

5 years ago

1.0.0-alpha-4

5 years ago

1.0.0-alpha-3

5 years ago

1.0.0-alpha-2

5 years ago

1.0.0-alpha-1

5 years ago

0.5.0

5 years ago

0.3.1

5 years ago

0.3.0

5 years ago

0.2.0

5 years ago

0.1.2

5 years ago

0.1.1

5 years ago

0.1.0

5 years ago