@combeenation/3d-viewer 8.0.0 → 9.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combeenation/3d-viewer",
-  "version": "8.0.0",
+  "version": "9.0.0",
   "description": "Combeenation 3D Viewer",
   "homepage": "https://github.com/Combeenation/3d-viewer#readme",
   "bugs": {
@@ -32,7 +32,7 @@
     "dist-full": "npm run clean-dist && npm run lint && cross-env NODE_ENV='production' webpack --config build/webpack.conf.js --progress && npm run replace-version",
     "docs-local": "typedoc --tsconfig tsconfig.json --media doc/assets --out docs-local",
     "docs-publish": "typedoc --tsconfig tsconfig.json --media doc/assets --out docs",
-    "format": "prettier --write .",
+    "format": "prettier --write ./src",
     "generate-profile": "cross-env NODE_ENV='dev' webpack --config build/webpack.conf.js --profile --json > dist/webpack-stats.json",
     "lint": "eslint src/**",
     "pack": "npm run dist-cjs && npm pack",
@@ -52,6 +52,7 @@
     "@babylonjs/serializers": "5.27.1",
     "eventemitter3": "4.0.7",
     "gsap": "3.11.2",
+    "is-svg": "^5.0.0",
     "lodash-es": "4.17.21"
   },
   "devDependencies": {

package/src/api/classes/element.ts

@@ -7,8 +7,9 @@ import {
   cloneTransformNode,
   cloneTransformNodeMaterial,
   deactivateTransformNode as deactivate,
+  drawPaintableOnMaterial,
   getClientRectFromMesh,
-  injectNodeMetadata,
+  injectMetadata,
   mapToDottedNodes,
   removeFromHighlightLayer,
   removeFromShadowGenerator,
@@ -16,7 +17,6 @@ import {
   setMaterialColor,
   setMaterialMetallness,
   setMaterialRoughness,
-  setMaterialTexture,
   setReceiveShadows,
   transformTransformNode,
 } from '../util/babylonHelper';
@@ -31,13 +31,12 @@ import { HighlightLayer } from '@babylonjs/core/Layers/highlightLayer';
 import { ShadowGenerator } from '@babylonjs/core/Lights/Shadows/shadowGenerator';
 import { Light } from '@babylonjs/core/Lights/light';
 import { PBRMaterial } from '@babylonjs/core/Materials/PBR/pbrMaterial';
-import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
 import { Material } from '@babylonjs/core/Materials/material';
 import { Color3 } from '@babylonjs/core/Maths/math.color';
 import { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
 import { Mesh } from '@babylonjs/core/Meshes/mesh';
 import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
-import { has, isArray, isNumber, isPlainObject, merge, union } from 'lodash-es';
+import { has, isArray, isNumber, merge, union } from 'lodash-es';
 
 /**
  * An {@link Element} of a {@link Variant}. Acts as a container for diverse definitions. Lives only in the context of a
@@ -320,7 +319,7 @@ export class Element extends VariantParameterizable {
       }
       if (!has(node.metadata, 'dirty.material.texture')) {
         // inject initial value and mark as dirty
-        injectNodeMetadata(node, { dirty: { material: { texture: true } } });
+        injectMetadata(node, { dirty: { material: { texture: true } } });
       }
     } else if (!node.material) {
       // paintables should also work if no material is assigned to the node per default
@@ -338,35 +337,26 @@ export class Element extends VariantParameterizable {
     // Removing this line will most likely break existing configurators, so be cautios!
     node.material.transparencyMode = Material.MATERIAL_ALPHATESTANDBLEND;
 
-    // consider width and height of the paintable
-    const widthAndHeight = {
-      width: imageSource.width,
-      height: imageSource.height,
-    };
     const paintableDefinition = this.getPaintableDefinition(paintable);
     if (isNumber(paintableDefinition.textureOptions)) {
-      widthAndHeight.width = paintableDefinition.textureOptions;
-      widthAndHeight.height = paintableDefinition.textureOptions;
-    } else if (isPlainObject(paintableDefinition.textureOptions)) {
-      widthAndHeight.width = paintableDefinition.textureOptions.width;
-      widthAndHeight.height = paintableDefinition.textureOptions.height;
+      // convert into object to satisfy the interface of `drawPaintableOnMaterial`
+      paintableDefinition.textureOptions = {
+        width: paintableDefinition.textureOptions,
+        height: paintableDefinition.textureOptions,
+      };
     }
 
-    // create dynamic texture on which the image can be drawn
-    const texture = new DynamicTexture(
-      `${this.id}.${paintable}.texture`,
-      widthAndHeight,
-      this.variant.viewer.scene,
-      false
-    );
-
-    // draw image on texture
-    const ctx = texture.getContext();
-    ctx.drawImage(imageSource, 0, 0);
-    texture.update(false);
+    // convert texture size options into scale values, as the scaling is now done via uvScale properties
+    const paintableOptions: PaintableOptions = {};
+    if (paintableDefinition.textureOptions.width) {
+      paintableOptions.uScale = paintableDefinition.textureOptions.width / (imageSource.width as number);
+    }
+    if (paintableDefinition.textureOptions.height) {
+      paintableOptions.vScale = paintableDefinition.textureOptions.height / (imageSource.height as number);
+    }
 
-    // finally apply the texture on the desired node material
-    setMaterialTexture(node, texture, false);
+    // forward to generic "paintable" call
+    drawPaintableOnMaterial(node.material, imageSource, this.variant.viewer.scene, paintableOptions);
 
     return this;
   }
@@ -435,12 +425,12 @@ export class Element extends VariantParameterizable {
           }
           // The default behaviour.
           element.nodes.forEach(node => {
-            injectNodeMetadata(node, { visibility: node.isEnabled() });
+            injectMetadata(node, { visibility: node.isEnabled() });
             activate(node);
           });
         } else if (visible === false) {
           element.nodes.forEach(node => {
-            injectNodeMetadata(node, { visibility: node.isEnabled() });
+            injectMetadata(node, { visibility: node.isEnabled() });
             deactivate(node);
           });
         }
@@ -514,7 +504,7 @@ export class Element extends VariantParameterizable {
             }
             if (!has(node.metadata, 'dirty.material.color')) {
               // inject initial value and mark as dirty
-              injectNodeMetadata(node, { dirty: { material: { color: oldValue } } });
+              injectMetadata(node, { dirty: { material: { color: oldValue } } });
             }
           }
           setMaterialColor(node, color);
@@ -532,7 +522,7 @@ export class Element extends VariantParameterizable {
             }
             if (!has(node.metadata, 'dirty.material.metallness')) {
               // inject initial value and mark as dirty
-              injectNodeMetadata(node, { dirty: { material: { metallness: oldValue } } });
+              injectMetadata(node, { dirty: { material: { metallness: oldValue } } });
             }
           }
           setMaterialMetallness(node, metallness);
@@ -550,7 +540,7 @@ export class Element extends VariantParameterizable {
             }
             if (!has(node.metadata, 'dirty.material.roughness')) {
               // inject initial value and mark as dirty
-              injectNodeMetadata(node, { dirty: { material: { roughness: oldValue } } });
+              injectMetadata(node, { dirty: { material: { roughness: oldValue } } });
             }
           }
           setMaterialRoughness(node, roughness);

package/src/api/classes/parameter.ts

@@ -139,6 +139,45 @@ export class Parameter {
    */
   public static readonly ROTATION = 'rotation';
 
+  /**
+   * Mutates the color.
+   *
+   * Scopes:
+   * * {@link Material} via {@link TagManager}
+   *
+   * @parser {@link parseColor}
+   */
+  public static readonly COLOR = 'color';
+
+  /**
+   * Mutates the metallic.
+   *
+   * Scopes:
+   * * {@link Material} via {@link TagManager}
+   *
+   * @parser {@link parseNumber}
+   */
+  public static readonly METALLIC = 'metallic';
+
+  /**
+   * Mutates the texture of a material, based on an svg string, image path or image data.
+   *
+   * Scopes:
+   * * {@link Material} via {@link TagManager}
+   *
+   */
+  public static readonly PAINTABLE = 'paintable';
+
+  /**
+   * Mutates the roughness.
+   *
+   * Scopes:
+   * * {@link Material} via {@link TagManager}
+   *
+   * @parser {@link parseNumber}
+   */
+  public static readonly ROUGHNESS = 'roughness';
+
   /**
    * Mutates whether a shadow should be casted or not.
    *
@@ -549,6 +588,76 @@ export class Parameter {
     return parseFloat(value.toString());
   }
 
+  /**
+   * Parses string defintion of a paintable into a paintable object.
+   * Here are some examples:
+   * - '{ "src": "pathToCertain.jpg", "uScale": 0.5 }' => default definition as JSON object
+   * - 'pathToCertain.jpg' => short hand definition, only contains source string
+   * - '{ "src": "pathToCertain.jpg", "uScale": -1, "vScale": -1, "uOffset": 0, "vOffset": 0 }' => full content,
+   *    paintable texture is flipped in both directions
+   * - '<svg>...</svg>' => SVG content can be used directly
+   * - { "src": "<svg>...</svg>", "uScale": 0.5 } => SVG in src property works as well
+   */
+  public static parsePaintableValue(value: ParameterValue): PaintableValue {
+    if (!isString(value)) {
+      throw new Error(`Unable to parse "${value}" to a PaintableValue: not a string.`);
+    }
+
+    const paintableValue: PaintableValue = { src: '' };
+    let valObj: { [key: string]: any } | null = null;
+
+    try {
+      valObj = JSON.parse(value);
+    } catch {
+      // use string directly
+      paintableValue.src = value;
+
+      if (value.startsWith('{')) {
+        // seems like the user tried to use a JSON string, as the input starts with {
+        throw new Error(`Unable to parse "${value}" to a PaintableValue: not a valid JSON string.`);
+      }
+    }
+
+    if (valObj) {
+      // input string is JSON, src attribute is required
+      if (!valObj.src) {
+        throw new Error(`Unable to parse "${value}" to a PaintableValue: property "src" is missing.`);
+      }
+
+      if (!isString(valObj.src)) {
+        throw new Error(`Unable to parse "${value}" to a PaintableValue: property "src" is not a string.`);
+      }
+
+      // split src and options
+      const { src, ...options } = valObj;
+      paintableValue.src = src;
+
+      // only forward valid paintable options
+      const validOptionKeys = ['uScale', 'vScale', 'uOffset', 'vOffset'];
+      const { validOptions, invalidKeys } = Object.entries(options).reduce(
+        (accRes, [curKey, curValue]) => {
+          const isValidKey = validOptionKeys.includes(curKey);
+          if (isValidKey) {
+            accRes.validOptions[curKey] = curValue;
+          } else {
+            accRes.invalidKeys.push(curKey);
+          }
+
+          return accRes;
+        },
+        { validOptions: {} as { [key: string]: any }, invalidKeys: [] as string[] }
+      );
+
+      if (invalidKeys.length) {
+        console.warn('parsePaintableValue: invalid paintable options provided: ' + invalidKeys.toString());
+      }
+
+      paintableValue.options = validOptions;
+    }
+
+    return paintableValue;
+  }
+
   /**
    * Parses a string with comma separated values to a list of strings.
    */

package/src/api/classes/variant.ts

@@ -1,7 +1,7 @@
 import {
   deactivateTransformNode,
   getDottedPathForNode,
-  injectNodeMetadata,
+  injectMetadata,
   intersectingNodeNames,
   reportDuplicateNodeNames,
 } from '../util/babylonHelper';
@@ -244,6 +244,20 @@ export class Variant extends Parameterizable {
     return this.elements.reduce((a, c) => [...a, ...c.nodesFlat], [] as TransformNode[]);
   }
 
+  /**
+   * The cloned Meshes of all {@link Element}s created for this {@link Variant} flattened.
+   */
+  get elementMeshesFlat(): Mesh[] {
+    return this.elements.reduce((a, c) => [...a, ...c.meshesFlat], [] as Mesh[]);
+  }
+
+  /**
+   * The cloned Meshes of all {@link Element}s created for this {@link Variant} flattened.
+   */
+  get elementAbstractMeshesFlat(): AbstractMesh[] {
+    return this.elements.reduce((a, c) => [...a, ...c.abstractMeshesFlat], [] as AbstractMesh[]);
+  }
+
   /**
    * All {@link Element}s from this {@link Variant}'s parents.
    */
@@ -662,16 +676,16 @@ export class Variant extends Parameterizable {
           );
           nodes.forEach(node => {
             deactivateTransformNode(node, false);
-            injectNodeMetadata(node, { dottedPath: getDottedPathForNode(node), originalName: node.name }, false);
+            injectMetadata(node, { dottedPath: getDottedPathForNode(node), originalName: node.name }, false);
           });
           this.assetContainer.lights.forEach(light => {
             light.setEnabled(false);
-            injectNodeMetadata(light, { dottedPath: getDottedPathForNode(light), originalName: light.name }, false);
+            injectMetadata(light, { dottedPath: getDottedPathForNode(light), originalName: light.name }, false);
             this.viewer.scene.addLight(light);
           });
           this.assetContainer.cameras.forEach(camera => {
             camera.setEnabled(false);
-            injectNodeMetadata(camera, { dottedPath: getDottedPathForNode(camera), originalName: camera.name }, false);
+            injectMetadata(camera, { dottedPath: getDottedPathForNode(camera), originalName: camera.name }, false);
             this.viewer.scene.addCamera(camera);
           });
           this.assetContainer.materials.forEach(material => this.viewer.scene.materials.push(material));
@@ -907,7 +921,7 @@ export class Variant extends Parameterizable {
     // inject node meta to all inherited elements
     // we do this to inject the deepest and most concrete variant information to all cloned nodes in the tree
     this.inheritedElements.forEach(element =>
-      element.nodes.forEach(node => injectNodeMetadata(node, { variant: this, variantParameterizable: element }))
+      element.nodes.forEach(node => injectMetadata(node, { variant: this, variantParameterizable: element }))
     );
     return this;
   }
@@ -920,7 +934,7 @@ export class Variant extends Parameterizable {
       this.viewerLights.push(await ViewerLight.create(this, name));
     }
     this.inheritedViewerLights.forEach(viewerLight => {
-      injectNodeMetadata(viewerLight.light, { variant: this, variantParameterizable: viewerLight });
+      injectMetadata(viewerLight.light, { variant: this, variantParameterizable: viewerLight });
     });
     return this;
   }

package/src/api/classes/viewer.ts

@@ -10,7 +10,7 @@ import { backgroundDomeName, envHelperMetadataName } from '../util/babylonHelper
 import { debounce, loadJavascript, loadJson } from '../util/resourceHelper';
 import { getCustomCbnBabylonLoaderPlugin } from '../util/sceneLoaderHelper';
 import { replaceDots } from '../util/stringHelper';
-import { isMeshIncludedInExclusionList } from '../util/structureHelper';
+import { isNodeIncludedInExclusionList } from '../util/structureHelper';
 import * as Index from './../../index';
 import { AnimationInterface } from './animationInterface';
 import { Event } from './event';
@@ -35,7 +35,7 @@ import { Mesh } from '@babylonjs/core/Meshes/mesh';
 import { ScreenshotTools } from '@babylonjs/core/Misc/screenshotTools';
 import { WebXRSessionManager } from '@babylonjs/core/XR/webXRSessionManager';
 import { Scene } from '@babylonjs/core/scene';
-import { isArray, isString } from 'lodash-es';
+import { isString } from 'lodash-es';
 
 /**
  * The main exposed object. This is the entry point into the application
@@ -308,6 +308,10 @@ export class Viewer extends EventBroadcaster {
       indexJson.scene = sceneJson;
     }
     this._scene = await this.initScene();
+    // set initial tag manager parameter values
+    if (tagManagerParameterValues) {
+      await this.tagManager.setParameterValues(tagManagerParameterValues);
+    }
     // create instance manager
     this._variantInstances = await VariantInstanceManager.create(this);
     // create optional default instances
@@ -317,7 +321,7 @@ export class Viewer extends EventBroadcaster {
         indexJson.setup = setupJson;
       }
       this.printInstanceDefinitions(indexJson.setup);
-      await this.createVariantInstances(tagManagerParameterValues);
+      await this.createVariantInstances();
     }
     this.broadcastEvent(Event.VARIANT_INSTANCES_READY, this);
     // create gltf export manager
@@ -486,7 +490,7 @@ export class Viewer extends EventBroadcaster {
         // ignore meshes with infinite distance, typically these are sky boxes
         const hasInfiniteDistance = mesh.infiniteDistance;
         // ignore excluded meshes
-        const isExcluded = excludeGeometry ? isMeshIncludedInExclusionList(mesh as Mesh, excludeGeometry) : false;
+        const isExcluded = excludeGeometry ? isNodeIncludedInExclusionList(mesh, excludeGeometry) : false;
         return isEnabled && isNotBBoxMesh && hasValidBBoxInfo && !hasInfiniteDistance && !isExcluded;
       })
       .reduce(
@@ -579,7 +583,7 @@ export class Viewer extends EventBroadcaster {
    * Resets everything by calling {@link destroy} to clear all references and {@link bootstrap} to setup a clean
    * environment
    */
-  public async reset(tagManagerParameterValues: TagManagerParameterValue[]): Promise<Viewer> {
+  public async reset(tagManagerParameterValues?: TagManagerParameterValue[]): Promise<Viewer> {
     await this.destroy();
     return this.bootstrap(tagManagerParameterValues);
   }
@@ -723,7 +727,7 @@ export class Viewer extends EventBroadcaster {
       this._cloneMaterialsOnMutation = sceneJson.cloneMaterialsOnMutation;
     }
     // register observers for tag manager
-    this.tagManager.registerNewTransformNodeObservers(scene);
+    this.tagManager.registerNewObjectObservers(scene);
     this.broadcastEvent(Event.SCENE_PROCESSING_END, scene);
     return scene;
   }
@@ -743,15 +747,10 @@ export class Viewer extends EventBroadcaster {
   /**
    * Batch creation of multiple {@link VariantInstance} objects with a {@link SetupJson} object passed
    */
-  protected async createVariantInstances(
-    tagManagerParameterValues?: TagManagerParameterValue[]
-  ): Promise<VariantInstance[]> {
+  protected async createVariantInstances(): Promise<VariantInstance[]> {
     const setupJson = SpecStorage.get<SetupJson>('setup');
     const instances: VariantInstance[] = [];
     for (const instanceDefinition of setupJson.instances) {
-      if (isArray(tagManagerParameterValues)) {
-        instanceDefinition.tagManagerParameterValues = tagManagerParameterValues;
-      }
       // don't create the instance right away if `lazy` is set, register it for later creation (on first usage) instead
       // however if the variant should be `visible` by default, `lazy` loading doesn't make sense and should therefore
       // be overruled by the `visible` flag
@@ -762,8 +761,7 @@ export class Viewer extends EventBroadcaster {
       const instance = await this.variantInstances.create(
         instanceDefinition.variant,
         instanceDefinition.name,
-        instanceDefinition.parameters,
-        instanceDefinition.tagManagerParameterValues
+        instanceDefinition.parameters
       );
       instances.push(instance);
     }

package/src/api/classes/viewerLight.ts

@@ -3,7 +3,7 @@ import {
   disableNodeWithParents,
   enableNodeWithParents,
   getRootNode,
-  injectNodeMetadata,
+  injectMetadata,
   transformTransformNode,
 } from './../util/babylonHelper';
 import { DottedPath } from './dottedPath';
@@ -294,7 +294,7 @@ export class ViewerLight extends VariantParameterizable {
       // Create pseudo parent since lights do not implement mutations like "rotation" by itself.
       babylonLight.parent = new TransformNode('__light__', this.variant.viewer.scene, true);
     }
-    injectNodeMetadata(babylonLight.parent, {
+    injectMetadata(babylonLight.parent, {
       variant: this.variant,
       variantParameterizable: this,
     });

package/src/api/manager/gltfExportManager.ts

@@ -1,5 +1,6 @@
 import { Viewer } from '../classes/viewer';
-import { isMeshIncludedInExclusionList } from '../util/structureHelper';
+import { injectMetadata } from '../util/babylonHelper';
+import { isNodeIncludedInExclusionList } from '../util/structureHelper';
 import { Engine } from '@babylonjs/core/Engines/engine';
 import { SceneLoader } from '@babylonjs/core/Loading/sceneLoader';
 import { PBRMaterial } from '@babylonjs/core/Materials/PBR/pbrMaterial';
@@ -15,6 +16,7 @@ import { has, merge } from 'lodash-es';
 type MetadataMap = { [key: string]: any };
 export class GltfExportManager {
   protected static readonly _CLONED_FROM_MAT_METADATA_PROPERTY = 'clonedFrom';
+  public static readonly NAME_BEFORE_EXPORT_METADATA_PROPERTY = 'nameBeforeExport';
 
   /**
    * Constructor.
@@ -111,7 +113,7 @@ export class GltfExportManager {
         if ((node.name as string).startsWith(Viewer.BOUNDING_BOX_NAME)) {
           return false;
         }
-        if (excluded && node instanceof Mesh && isMeshIncludedInExclusionList(node, excluded)) {
+        if (excluded && node instanceof TransformNode && isNodeIncludedInExclusionList(node, excluded)) {
           return false;
         }
         return true;
@@ -268,7 +270,10 @@ export class GltfExportManager {
    */
   protected setUniqueMeshNames(scene: Scene): void {
     const allNodes = scene.getNodes().filter(node => node instanceof TransformNode) as TransformNode[];
-    allNodes.forEach(currMesh => (currMesh.name = `${currMesh.name}_${currMesh.uniqueId}`));
+    allNodes.forEach(currMesh => {
+      injectMetadata(currMesh, { [GltfExportManager.NAME_BEFORE_EXPORT_METADATA_PROPERTY]: currMesh.name }, false);
+      currMesh.name = `${currMesh.name}_${currMesh.uniqueId}`;
+    });
   }
 
   /**