@combeenation/3d-viewer 0.0.1-types

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2020 Combeenation GmbH
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,111 @@
+# 3D viewer
+
+## Usage
+
+- Create a label called `JS_3dViewerLbl` which we'll use to render the 3d viewer into:
+
+  - Set its value to `<canvas></canvas>`
+  - Add CSS class `ViewerLbl`
+  - Add the following CSS styles to your configurator:
+
+    ```css
+    .ViewerLbl .cfgrctrl-innerlabel {
+      height: 100%;
+    }
+
+    .ViewerLbl canvas {
+      width: 100%;
+      height: 100%;
+    }
+    ```
+
+- Install viewer dependencies: `npm i @combeenation/3d-viewer`
+- Create specification (example, bare minimum):
+  ```js
+  /**
+   * @return {StructureJson}
+   */
+  export function createSpec() {
+    return {
+      scene: {
+        engine: {
+          antialiasing: true,
+          options: {
+            preserveDrawingBuffer: true,
+            stencil: true,
+            // `xrCompatible` is required to fix WebXR issue in Safari 15 as mentioned in the Babylon.js forum:
+            // https://forum.babylonjs.com/t/safari-15-0-breaks-every-babylonjs-application/23973
+            xrCompatible: false,
+          },
+        },
+        scene: {
+          globals: {},
+          cameras: {},
+        },
+      },
+      setup: {
+        instances: [
+          {
+            name: 'DirtBikeInstance',
+            variant: 'DirtBike',
+            lazy: false,
+            parameters: {
+              visible: true,
+              scaling: '( 1, 1, 1 )',
+              position: '( 0, 0, 0 )',
+              rotation: '( 0, 0, 0 )',
+            },
+          },
+        ],
+      },
+      variants: {
+        DirtBike: {
+          glTF: 'https://combeepublic.blob.core.windows.net/resources/the-3d-file.glb',
+          elements: {
+            Main: ['__root__'],
+          },
+        },
+      },
+    };
+  }
+  ```
+- Bootstrap viewer (example code):
+
+  ```js
+  import { Viewer } from '@combeenation/3d-viewer';
+  import { CtrlUtils } from '@combeenation/custom-js-utils';
+  import { createSpec } from 'path/to/spec-file';
+
+  /**
+   * Bootstraps the viewer using the JSON spec, registers all needed events etc.
+   */
+  export async function bootstrapViewer() {
+    Cbn.utils.Log.add(`Bootstrapping viewer v${Viewer.version}`, Cbn.utils.Log.Type.Misc)();
+
+    const $canvas = $(CtrlUtils.getLabel('JS_3dViewerLbl').el.dom).find('canvas');
+    const canvas = /** @type {HTMLCanvasElement} */ ($canvas.get(0));
+    const viewer = new Viewer(canvas, createSpec());
+    await viewer.bootstrap([]);
+
+    // The resize listener doesn't seem to work on the canvas itself, therefore we're installing it on its parent
+    Cbn.utils.ResizeEvents.addResizeListener(canvas.parentElement, () => viewer.resize());
+
+    return viewer;
+  }
+  ```
+
+- Call `bootstrapViewer` e.g. somewhere in `onCfgrReady` in your main file:
+
+  ```js
+  CfgrUtils.onCfgrReady(async () => {
+    // ...
+
+    const viewer = await bootstrapViewer();
+
+    // ...
+
+    // Make some functions accessible in the global window object (e.g. for debugging in the console etc.)
+    // Can be extended as needed.
+    window.CfgrJS = { /* ... */ viewer /* ... */ };
+  });
+  ```