@combeenation/3d-viewer 0.0.1

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 /* ... */ };
+  });
+  ```

package/dist/types/api/classes/animationInterface.d.ts

@@ -0,0 +1,8 @@
+/**
+ * An Interface defining the basic functionality of an animation.
+ */
+export interface AnimationInterface {
+    play(): Promise<AnimationInterface>;
+    pause(): AnimationInterface;
+    kill(): AnimationInterface;
+}

package/dist/types/api/classes/dottedPath.d.ts

@@ -0,0 +1,79 @@
+export declare class DottedPath {
+    static DELIMITER: string;
+    static SAFE_CHAR: string;
+    parts: string[];
+    /**
+     * Magic factory function that creates a DottedPath based on the argument type.
+     */
+    static create(dottedPath?: DottedPathArgument): DottedPath;
+    /**
+     * Creates a DottedPath from a string.
+     * Allows patterns with unsafe characters wrapped in apostrophes or quotes.
+     * E.g. "part1.part2.'part.3'.part_4"
+     */
+    static createFromPath(path: string): DottedPath;
+    /**
+     * Creates a DottedPath from a string list.
+     */
+    static createFromParts(parts: string[]): DottedPath;
+    /**
+     * Creates an empty DottedPath.
+     */
+    static createEmpty(): DottedPath;
+    /**
+     * Sanitizes given part: replaces all characters like {@link DottedPath.DELIMITER}
+     * with a "safe" character like {@link DottedPath.SAFE_CHAR}.
+     * (i) Does not trim whitespace.
+     */
+    static sanitizePart(part: string): string;
+    /**
+     * Constructor
+     */
+    private constructor();
+    /**
+     * The path.
+     * (i) Does not return an empty dot for no path.
+     */
+    get path(): string;
+    /**
+     * The first part.
+     */
+    get firstPart(): string | null;
+    /**
+     * The last part.
+     */
+    get lastPart(): string | null;
+    /**
+     * Gets the tokens to each leaf of the DottedPath tree.
+     * E.g. "part1.part2.part_3" will return an array like
+     *      ["part1", "part1.part2", "part1.part2.part_3"]
+     */
+    get leafTokens(): string[];
+    /**
+     * Removes the first part and returns it.
+     */
+    shiftPart(): string | undefined;
+    /**
+     * Adds part to the beginning of parts list.
+     */
+    unshiftPart(part: string, duplicateCheck?: boolean): DottedPath;
+    /**
+     * Adds part to the end of parts list.
+     * (i) Does not add a part if the last char already is the delimiter or if an empty string was passed.
+     */
+    addPart(part: string, duplicateCheck?: boolean): DottedPath;
+    /**
+     * Adds multiple parts to the end of parts list.
+     */
+    addParts(parts: string[], duplicateCheck?: boolean): DottedPath;
+    /**
+     * Removes the last part and returns it.
+     */
+    popPart(): string | undefined;
+    toString(): string;
+    valueOf(): string;
+    /**
+     * Clones the DottedPath.
+     */
+    clone(): DottedPath;
+}

package/dist/types/api/classes/element.d.ts

@@ -0,0 +1,153 @@
+import { VariantParameterizable } from './../classes/variantParameterizable';
+import { DottedPath } from './dottedPath';
+import { Variant } from './variant';
+import { HighlightLayer } from '@babylonjs/core/Layers/highlightLayer';
+import { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
+import { Mesh } from '@babylonjs/core/Meshes/mesh';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+/**
+ * An {@link Element} of a {@link Variant}. Acts as a container for diverse definitions. Lives only in the context of a
+ * {@link Variant}.
+ *
+ * When used in typings, refer to via its alias {@link VariantElement} to prevent name clashes with the web APIs
+ * [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) class
+ */
+export declare class Element extends VariantParameterizable {
+    readonly variant: Variant;
+    readonly name: string;
+    readonly nodes: TransformNode[];
+    protected readonly _dottedNodes: Map<DottedPath, TransformNode>;
+    protected _highlightLayer?: HighlightLayer;
+    /**
+     * Constructor.
+     */
+    protected constructor(variant: Variant, name: string);
+    /**
+     * Creates an {@link Element} with given name.
+     */
+    static create(variant: Variant, name: string): Promise<Element>;
+    /**
+     * The {@link DottedPath} in the built tree of {@link Element}s.
+     * E.g. "_.top-1.sub-2.sub-sub-3.el-1"
+     */
+    get dottedPath(): DottedPath;
+    /**
+     * The id representing a {@link DottedPath}.
+     */
+    get id(): string;
+    /**
+     * The {@link ElementDefinition} of the {@link Element}.
+     */
+    get definition(): ElementDefinition;
+    /**
+     * The {@link PathDefinitions} of the {@link Element}.
+     */
+    get pathDefinitions(): PathDefinitions;
+    /**
+     * The {@link TraceableDefinitions} of the {@link Element}.
+     */
+    get traceableDefinitions(): TraceableDefinitions;
+    /**
+     * The {@link PaintableDefinition} of the {@link Element}.
+     */
+    get paintableDefinitions(): PaintableDefinitions;
+    /**
+     * The inherited {@link ParameterBag}.
+     * Merges the {@link Variant}'s parameters and those from the {@link Element}.
+     */
+    get inheritedParameters(): ParameterBag;
+    /**
+     * The actual {@link TransformNode}s that make up this {@link Element}.
+     */
+    get nodesFlat(): TransformNode[];
+    /**
+     * The actual {@link Mesh}es that make up this {@link Element}.
+     * Handy for e.g. creating a bounding box around an entire element.
+     */
+    get meshesFlat(): Mesh[];
+    /**
+     * The actual {@link AbstractMesh}es that make up this {@link Element}.
+     * I.e. (real) Meshes as well as InstancedMeshes.
+     */
+    get abstractMeshesFlat(): AbstractMesh[];
+    /**
+     * The meshes of this {@link Element}.
+     */
+    get meshes(): Mesh[];
+    /**
+     * @protected
+     */
+    set highlightLayer(layer: HighlightLayer | undefined);
+    get highlightLayer(): HighlightLayer | undefined;
+    /**
+     * Destroys this {@link Element} and dispose all nodes.
+     */
+    destroy(): Element;
+    /**
+     * Gets a node by its {@link DottedPath}.
+     */
+    getNode(dottedPath: DottedPathArgument): TransformNode;
+    /**
+     * Gets a mesh by its {@link DottedPath}.
+     */
+    getMesh(dottedPath: DottedPathArgument): Promise<Mesh | null>;
+    /**
+     * Gets a {@link PaintableDefinition} by its name.
+     */
+    getPaintableDefinition(name: string): PaintableDefinition;
+    /**
+     * Gets a {@link TraceableDefinition} by its name.
+     */
+    getTraceableDefinition(name: string): TraceableDefinition;
+    /**
+     * Gets the paintable Node by its name.
+     */
+    getPaintableNode(name: string): TransformNode;
+    /**
+     * Gets the traceable Node by its name.
+     */
+    getTraceableNode(name: string): TransformNode;
+    /**
+     * @see {@link VariantParameterizable.commitParameters}
+     * @emit {@link Event.ELEMENT_PARAMETER_COMMITTED}
+     */
+    commitParameters(parameters?: ParameterBag): Promise<VariantParameterizable>;
+    /**
+     * Adds an observer function for camera matrix changes.
+     * The `observer` gets 2 parameters: the `AbstractMesh` and a `ClientRect` object.
+     */
+    addTraceableObserver(traceable: string, observer: CallableFunction, payload?: any): Element;
+    /**
+     * Draws a `ImageBitmap` or `OffscreenCanvas` onto a `paintable` defined via {@link PaintableDefinition}.
+     */
+    drawPaintable(paintable: string, imageSource: CanvasImageSource): Element;
+    /**
+     * Draws a SVG string onto a `paintable` defined via {@link PaintableDefinition}.
+     */
+    drawPaintableFromSvg(paintable: string, svgSource: string): Promise<Element>;
+    /**
+     * Draws an Image from source (URL/URI) onto a `paintable` defined via {@link PaintableDefinition}.
+     */
+    drawPaintableFromImgSrc(paintable: string, imgSource: string): Promise<Element>;
+    /**
+     * Adds observers for loading missing materials where needed
+     */
+    protected addMissingMaterialObservers(): void;
+    /**
+     * Adds the default {@link ParameterObserver}s which are called every time {@link commitParameters} is called.
+     */
+    protected addParameterObservers(): Element;
+    /**
+     * Filter for nodes that are not defined or excluded in the `pathDefinitions`.
+     */
+    protected filterNode(node: TransformNode): boolean;
+    /**
+     * Asserts whether all {@link pathDefinitions} link to a valid `Node` path.
+     * @protected
+     */
+    protected assertPathDefinitions(): void;
+    /**
+     * Handles callback for given light parameter.
+     */
+    private castShadowValueHandler;
+}