4.20.1 • Published 8 months ago

@cognite/reveal v4.20.1

Weekly downloads
476
License
Apache-2.0
Repository
github
Last release
8 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

8 months ago

4.20.1

8 months ago

4.19.1

9 months ago

4.19.0

9 months ago

4.18.0

9 months ago

4.17.1-dev.20240925

10 months ago

4.17.1-dev.20240924

10 months ago

4.16.1-dev.20240829

10 months ago

4.16.1-dev.20240828

10 months ago

4.16.1-dev.20240827

10 months ago

4.16.1-dev.20240826

11 months ago

4.17.0-dev.20240830

10 months ago

4.17.1-dev.20240905

10 months ago

4.17.1-dev.20240904

10 months ago

4.17.1-dev.20240906

10 months ago

4.17.1-dev.20240909

10 months ago

4.17.1-dev.20240903

10 months ago

4.17.1-dev.20240920

10 months ago

4.17.1-dev.20240923

10 months ago

4.17.1-dev.20240916

10 months ago

4.17.1-dev.20240918

10 months ago

4.17.1-dev.20240917

10 months ago

4.17.1-dev.20240919

10 months ago

4.17.1-dev.20240910

10 months ago

4.17.1-dev.20240912

10 months ago

4.17.1-dev.20240911

10 months ago

4.17.1-dev.20240913

10 months ago

4.17.0-dev.20240902

10 months ago

4.17.0

10 months ago

4.17.1

10 months ago

4.16.1-dev.20240821

11 months ago

4.14.5

1 year ago

4.16.1-dev.20240820

11 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

11 months ago

4.14.4

1 year ago

4.14.9

1 year ago

4.16.1-dev.20240802

11 months ago

4.16.1-dev.20240801

11 months ago

4.16.1-dev.20240807

11 months ago

4.16.1-dev.20240806

11 months ago

4.16.1-dev.20240805

11 months ago

4.16.1-dev.20240809

11 months ago

4.16.1-dev.20240808

11 months ago

4.16.1-dev.20240814

11 months ago

4.16.1-dev.20240813

11 months ago

4.16.1-dev.20240812

11 months ago

4.16.1-dev.20240816

11 months ago

4.16.1-dev.20240815

11 months ago

4.16.1-dev.20240819

11 months ago

4.16.0

12 months ago

4.16.1

12 months ago

4.15.1-dev.20240709

12 months ago

4.15.1-dev.20240708

12 months ago

4.15.2-dev.20240726

12 months ago

4.15.2-dev.20240725

12 months ago

4.15.2-dev.20240724

12 months ago

4.15.2-dev.20240723

12 months ago

4.15.0

1 year ago

4.15.1

1 year ago

4.15.2

12 months ago

4.15.1-dev.20240719

12 months ago

4.15.1-dev.20240716

12 months ago

4.15.1-dev.20240715

12 months ago

4.15.1-dev.20240718

12 months ago

4.15.1-dev.20240717

12 months ago

4.15.1-dev.20240712

12 months ago

4.15.1-dev.20240711

12 months ago

4.15.1-dev.20240710

12 months ago

4.15.1-dev.20240722

12 months ago

4.16.1-dev.20240729

11 months ago

4.16.1-dev.20240731

11 months ago

4.16.1-dev.20240730

11 months 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

1 year 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

2 years ago

4.1.1

2 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

3 years ago

3.0.0-alpha.0

3 years ago

3.0.0-alpha.2

3 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