Merge remote-tracking branch 'origin/master' into greenbech/add-groun…

…d-plane-rotation
cognitedata · Jun 28, 2024 · 8e2ad12 · 8e2ad12
2 parents 1b527f6 + bef7e2e
commit 8e2ad12
Show file tree

Hide file tree

Showing 386 changed files with 26,021 additions and 19,385 deletions.
diff --git a/RELEASING.md b/RELEASING.md
@@ -2,40 +2,27 @@ Releasing Reveal involves releasing NPM packages `@cognite/reveal` and/or updati
 deployed when pushed to master.
 
 # Publishing packages
-Publishing of new packages to NPM is handled automatically by a Github Actions workflow which is triggered when publishing a new release on GitHub.
-The only consideration you need to make when publishing a new release, is that the NPM package version must be unique meaning that the package version has not been released previously.
 
-### Updating latest documentation
-To update the documentation with any changes that might have been added since the last release:
-
-Assuming you are at the root of the project navigate do the documentation folder and run the update script
-
-```bash
-
-cd documentation
-
-# replaces the 'latest' documentation by the 'next'
-yarn replace-latest-by-next
-```
-
-1. Commit these changes
+### Update the package version
 
-2. Create a PR with the changes.
+First, Reveal's package version must be incremented. This is done by changing the "version" field at the top of `viewer/package.json`. We use [semantic versioning](https://semver.org/#summary). Increment patch version if the changes are purely internal or only affects experimental features (so e.g. 4.14.1 becomes 4.14.2), or increment minor version if there are new features added (new types, functions, classes, new fields in already-existing types).
 
-Once the PR is merged into master, the documentation will be automatically deployed.
+Submit a PR with the version number update. Make sure it has been merged before continuing with the next steps.
 
 ### Create a release on GitHub
 
 1. Go to [https://github.com/cognitedata/reveal/releases/new](https://github.com/cognitedata/reveal/releases/new)
 2. Under the "Tag version" field, add a new tag for this release with the name and version of the package, e.g. `@cognite/reveal@3.2.0`
 3. Specify the same release title as the tag name.
-4. Write the changes that new version brings. Get inspired by done tasks from your sprint board. Note!
-   Remember to specify the correct ThreeJS version required by the released version - you can find this in package.json
-   of the viewer.
-Also, you can check what's committed from the previous tag with that command:
+4. Write the changes that new version brings. Use the commit history. You can check what's committed from the previous tag (in this case, 3.1.9) with this command:
    ```bash
-   git log --pretty=format:"* %s" @cognite/reveal@3.2.0...HEAD
+   git log --pretty=format:"* %s" @cognite/reveal@3.1.9...HEAD
    ```
+
+Note!
+   Remember to specify the correct ThreeJS version required by the released version - you can find this in package.json
+   of the viewer.
+
     Use the following template:
 ```
 This version of Reveal is compatible with ThreeJS <THREEJS_VERSION>.
@@ -60,3 +47,27 @@ This version of Reveal is compatible with ThreeJS <THREEJS_VERSION>.
 See [installation documentation](https://cognitedata.github.io/reveal-docs/docs/installation) for details about installing Reveal.
 ```
 5. Hit the green "Publish release" button
+
+
+### Publish the NPM package
+
+Then, to publish the NPM package, go to Actions at the top of the Github-page, then find "Publish Package to NPM" to the right. Click "Run workflow", and the package should be underway.
+
+### Updating latest documentation
+To update the documentation with any changes that might have been added since the last release:
+
+Assuming you are at the root of the project navigate do the documentation folder and run the update script
+
+```bash
+
+cd documentation
+
+# replaces the 'latest' documentation by the 'next'
+yarn replace-latest-by-next
+```
+
+1. Commit these changes
+
+2. Create a PR with the changes.
+
+Once the PR is merged into master, the documentation will be automatically deployed.
diff --git a/documentation/docs/api_readme.md b/documentation/docs/api_readme.md
@@ -1,8 +1,8 @@
 `@cognite/reveal` supports `Node16` [module resolution](https://www.typescriptlang.org/tsconfig#moduleResolution), and if enabled in the consuming application will expose three modules:
-- [@cognite/reveal](/api/modules/cognite_reveal.md) is the main module and has the main entry point of Reveal, [`Cognite3DViewer`](/api/classes/cognite_reveal.Cognite3DViewer.md). CAD models are represented by [`CogniteCadModel`](/api/classes/cognite_reveal.CogniteCadModel.md) and points clouds by [`CognitePointCloudModel`](/api/classes/cognite_reveal.CognitePointCloudModel.md).
-- [@congite/reveal/tools](/api/modules/cognite_reveal_tools.md) contains a set of tools, e.g. [`AxisViewTool`](/api/classes/cognite_reveal_tools.AxisViewTool.md), [`TimelineTool`](/api/classes/cognite_reveal_tools.TimelineTool.md), and [`HtmlOverlayTool`](/api/classes/cognite_reveal_tools.HtmlOverlayTool.md) that works with `Cognite3DViewer`.
-- [@cognite/reveal/extensions/datasource](/api/modules/cognite_reveal_extensions_datasource.md) allows providing custom data sources for geometry and model metadata.
+- [@cognite/reveal](/api/@cognite/reveal/index.md) is the main module and has the main entry point of Reveal, [`Cognite3DViewer`](/api/@cognite/reveal/classes/Cognite3DViewer.md). CAD models are represented by [`CogniteCadModel`](/api/@cognite/reveal/classes/CogniteCadModel.md) and points clouds by [`CognitePointCloudModel`](/api/@cognite/reveal/classes/CognitePointCloudModel.md).
+- [@congite/reveal/tools](/api/@cognite/reveal/tools/index.md) contains a set of tools, e.g. [`AxisViewTool`](/api/@cognite/reveal/tools/classes/AxisViewTool.md), [`TimelineTool`](/api/@cognite/reveal/tools/classes/TimelineTool.md), and [`HtmlOverlayTool`](/api/@cognite/reveal/tools/classes/HtmlOverlayTool.md) that works with `Cognite3DViewer`.
+- [@cognite/reveal/extensions/datasource](/api/@cognite/reveal/extensions/datasource/index.md) allows providing custom data sources for geometry and model metadata.
 
 :::note
 If the consuming application does not enable `Node16` module resolution, then all types must be imported from `@cognite/reveal`.
-:::
+:::
diff --git a/documentation/docs/components/LiveCodeSnippet.tsx b/documentation/docs/components/LiveCodeSnippet.tsx
@@ -65,7 +65,6 @@ function transformCode(code: string): string {
             }
 
             if (viewer) {
-              resetViewerEventHandlers(viewer);
               if (model instanceof CogniteCadModel) {
                 resetCogniteCadModel(model);
               }
@@ -85,7 +84,6 @@ function onRunCode(code: string) {
 }
 
 export const LiveCodeSnippet = (props: LiveCodeSnippetProps) => {
-
   let code: string = props.children;
   function setCode(newCode: string) {
     code = newCode;
@@ -118,3 +116,5 @@ export const LiveCodeSnippet = (props: LiveCodeSnippetProps) => {
     </button>
   </>);
 };
+
+export default LiveCodeSnippet;
diff --git a/documentation/docs/examples/cad-save-viewerstate.mdx b/documentation/docs/examples/cad-save-viewerstate.mdx
@@ -59,7 +59,7 @@ const myState = {
         "renderGhosted": true
       },
       "modelId": 3356984403684032,
-      "revisionId": 6664823881595566,
+      "revisionId": 6049696084265067,
       "styledSets": [
         {
           "token": "PropertyFilterNodeCollection",

diff --git a/documentation/docs/examples/image360.mdx b/documentation/docs/examples/image360.mdx
@@ -7,15 +7,15 @@ description: Using and displaying 360 images using Reveal
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
 360 images is a common way to augment the 3D experience of your application.
-A 360 image is a controllable panoramic image that surrounds the original point from which the shot was taken. 
+A 360 image is a controllable panoramic image that surrounds the original point from which the shot was taken.
 360 images simulate being in the shoes of a photographer and looking around to the left, right, up and down as desired as well as zooming.
 
 The `Cognite3DViewer` entrypoint exposes the following methods related to 360 images.
 
 ```ts
 add360ImageSet(
-  datasource: 'events', 
-  eventFilter: { [key: string]: string }, 
+  datasource: 'events',
+  eventFilter: { [key: string]: string },
   add360ImageOptions?: AddImage360Options
 ): Promise<Image360Collection>;
 
@@ -27,17 +27,17 @@ exit360Image(): void
 ```
 
 To visualize 360 images the data must have been previously ingested into [Cognite Data Fusion](https://www.cognite.com/en/product/cognite_data_fusion_industrial_dataops_platform).
-More info on the ingestion process can be found [here](https://docs.cognite.com/cdf/3d/guides/360images_upload/).
+More info on the ingestion process for 360 images can be found [here](https://docs.cognite.com/cdf/3d/guides/360images_upload/).
 
 Once the data is ingested, a set of 360 images can be added to the viewer with `viewer.add360ImageSet(...)`.
 `datasource` describes the source data type used for storing the 360 images.
-At this time, the only valid `datasource` is `'events'`, but you can expect more to be added in the future.
-The `eventFilter` property describes the filter that is used when fetching data from the data source.
-This is a generic key-value pair and can point to any metdata that was set during ingestion.
+Currently, the supported `datasource`s are `'events'` and `'datamodels'`.
+The `second` argument describes the filter that is used when fetching data from the data source.
+For events, this is a generic key-value pair and can point to any metdata that was set during ingestion. For datamodels, this is an identifier consisting of the Data Models `externalId` and `space` of the relevant 360 collection instance.
 `viewer.add360ImageSet(...)` will return a `Image360Collection` which contains each of the `image360` entities for this given set.
-The definition of `Image360Collection` can be found [here.](../api/interfaces/cognite_reveal.Image360Collection)
+The definition of `Image360Collection` can be found [here.](../api/@cognite/reveal/interfaces/Image360Collection)
 
-The `AddImage360Options` is used for correcting / adding transformations to the set of 360 images. The declaration can be found [here.](../api/modules/cognite_reveal#addimage360options)
+The `AddImage360Options` is used for correcting / adding transformations to the set of 360 images. The declaration can be found [here.](../api/@cognite/reveal/type-aliases/AddImage360Options)
 
 :::note
 The 360 images should be ingested with proper transformation data, and one should only rely on `AddImage360Options` when failing to do so or when using the same 360 images for multiple 3D models with different coordinate system.
@@ -63,11 +63,11 @@ An example of entering into a 360 image can be seen here:
 
 To remove one or more 360 images you can use the `remove360Images(...)` method which will also cleanup icons and other related data to the instance.
 
-The `Image360` declaration can be found here [here.](../api/interfaces/cognite_reveal.Image360)
+The `Image360` declaration can be found here [here.](../api/@cognite/reveal/interfaces/Image360)
 
 The `transform` property from `Image360` represents the world transformation (rotation and translation) of the 360 image.
 The `Image360Visualization` object has convenience functionality related to the visualization of the 360 image such as setting the opacity of the given 360 image.
-  
+
 ## Events
 The `Image360Collection` exposes events `image360Entered` and `image360Exited` for subscribing to enter & exit from 360 image mode. The `image360Entered` event is also triggered when the [revision](#historical-images) of an image is changed.
 Subscribing to the events can look like
@@ -104,4 +104,4 @@ const revisions = image360.getRevisions();
 const newRevision = revisions[1];
 await viewer.enter360Image(image360, newRevision);
 alert(`Revision changed to ${newRevision.date}`);
-```
+```
diff --git a/documentation/docs/extending/camera-manager.mdx b/documentation/docs/extending/camera-manager.mdx
@@ -17,7 +17,7 @@ In certain cases it can be useful to customize behaviour of the camera:
 
 To create a custom camera manager class, `CameraManager` interface from `@cognite/reveal` must be implemented
 and provided to `Cognite3DViewer` on construction using the `cameraManager`-option. You can also set camera manager
-in runtime by calling `setCameraManager` method of `Cognite3DViewer` class. Interface is defined [here in the API reference](../api/interfaces/cognite_reveal.CameraManager.md).
+in runtime by calling `setCameraManager` method of `Cognite3DViewer` class. Interface is defined [here in the API reference](../api/@cognite/reveal/interfaces/CameraManager.md).
 
 Main implementation specific functions are `setCameraState`, `fitCameraToBoundingBox` and `update`.
 Setting state shouldn't be possible when `rotation` and `target` are passed at the same time because they could conflict.
@@ -160,4 +160,4 @@ the behaviour of camera controls (`OrbitControls` in this case). For calculating
 
 3. Inside `update` method you should update `near` and `far` planes of the camera, which can be easily done using `updateCameraNearAndFar` method of `CameraManagerHelper`.
 
-4. The functions `activate` and `deactivate` are called automatically when a new CameraManager is assigned to the Cognite3DViewer. These functions are intended to help manage enabling and disabling of input when the manager changes state. Return value of `get enabled` should reflect this state.
+4. The functions `activate` and `deactivate` are called automatically when a new CameraManager is assigned to the Cognite3DViewer. These functions are intended to help manage enabling and disabling of input when the manager changes state. Return value of `get enabled` should reflect this state.
diff --git a/documentation/docs/utils/viewerUtilities.ts b/documentation/docs/utils/viewerUtilities.ts
@@ -1,20 +1,8 @@
 import {
   CogniteCadModel,
-  Cognite3DViewer,
   DefaultNodeAppearance,
 } from '@cognite/reveal';
 
-/**
- * Resets all event handlers on the viewer provided. This uses
- * internal functionality and actual applications needs to implement
- * this to better approaches than this.
- */
-export function resetViewerEventHandlers(viewer: Cognite3DViewer): void {
-  const eventListeners = (viewer as any)._events;
-  eventListeners.cameraChange.unsubscribeAll();
-  eventListeners.click.unsubscribeAll();
-  eventListeners.hover.unsubscribeAll();
-}
 
 /**
  * Resets state of model to the default state (i.e. appearance and styled sets)

diff --git a/documentation/docusaurus.config.js b/documentation/docusaurus.config.js
@@ -1,4 +1,6 @@
-module.exports = {
+import { themes } from 'prism-react-renderer';
+
+export default {
   title: 'Reveal docs',
   tagline: '@cognite/reveal documentation site',
   url: 'https://cognitedata.github.io',
@@ -17,7 +19,7 @@ module.exports = {
     },
     prism: {
       // changes syntax highlighting theme
-      theme: require('prism-react-renderer/themes/oceanicNext'),
+      theme: themes.oceaticNext
     },
     navbar: {
       title: '@cognite/reveal',
@@ -85,9 +87,9 @@ module.exports = {
 };
 
 /*
-* By default autogenerated sidebars are sorted alphabetically by path and filename. 
+* By default autogenerated sidebars are sorted alphabetically by path and filename.
 * This function is used to allow items in the same folder to be sorted alphabetically by label.
-* 
+*
 * Documentation for sidebarItemsGenerator: https://docusaurus.io/docs/sidebar/autogenerated
 */
 function recursiveSortByLabel(items) {

diff --git a/documentation/package.json b/documentation/package.json
@@ -26,9 +26,9 @@
   "dependencies": {
     "@azure/msal-browser": "3.17.0",
     "@codemirror/lang-javascript": "6.2.2",
-    "@docusaurus/core": "2.4.3",
-    "@docusaurus/preset-classic": "2.4.3",
-    "@docusaurus/remark-plugin-npm2yarn": "2.4.3",
+    "@docusaurus/core": "3.4.0",
+    "@docusaurus/preset-classic": "3.4.0",
+    "@docusaurus/remark-plugin-npm2yarn": "3.4.0",
     "@uiw/codemirror-theme-material": "4.22.2",
     "@uiw/react-codemirror": "4.22.2",
     "clsx": "2.1.1",
@@ -41,13 +41,13 @@
   "devDependencies": {
     "@types/react": "18.3.3",
     "copyfiles": "2.4.1",
-    "docusaurus-plugin-typedoc": "0.22.0",
+    "docusaurus-plugin-typedoc": "1.0.1",
     "replace": "1.2.2",
     "rimraf": "5.0.7",
-    "typedoc": "0.25.13",
-    "typedoc-plugin-markdown": "3.17.1",
+    "typedoc": "0.26.2",
+    "typedoc-plugin-markdown": "4.1.0",
     "typedoc-plugin-no-inherit": "1.4.0",
-    "typescript": "5.4.5"
+    "typescript": "5.5.2"
   },
   "browserslist": {
     "production": [