@combeenation/3d-viewer 6.2.1 → 6.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combeenation/3d-viewer",
-  "version": "6.2.1",
+  "version": "6.4.0",
   "description": "Combeenation 3D Viewer",
   "homepage": "https://github.com/Combeenation/3d-viewer#readme",
   "bugs": {
@@ -24,8 +24,8 @@
     "src"
   ],
   "scripts": {
-    "clean-dist": "rimraf dist",
     "bundle-analyzer": "npm run generate-profile && webpack-bundle-analyzer dist/webpack-stats.json dist/lib-full",
+    "clean-dist": "rimraf dist",
     "dev": "cross-env NODE_ENV='dev' webpack serve --config build/webpack.conf.js --progress --hot",
     "dist-cjs": "npm run clean-dist && npm run lint && tsc --project commonjs.tsconfig.json && npm run replace-version",
     "dist-es6": "npm run clean-dist && npm run lint && tsc --project es6.tsconfig.json && npm run replace-version",

package/src/api/classes/element.ts

@@ -441,7 +441,7 @@ export class Element extends VariantParameterizable {
     this._parameterObservers.set(Parameter.MATERIAL, [
       async (element: Element, oldValue: ParameterValue, newValue: ParameterValue) => {
         const materialName = newValue.toString();
-        element.nodes.forEach(node => {
+        for (const node of element.nodes) {
           assertTransformNode(node, (node: AbstractMesh) => {
             if (node instanceof InstancedMesh) {
               throw new Error(
@@ -451,8 +451,8 @@ export class Element extends VariantParameterizable {
               );
             }
           });
-          setMaterial(element.variant, node, materialName);
-        });
+          setMaterial(element.variant.viewer.scene, node, materialName, true, element.variant);
+        }
       },
     ]);
     this._parameterObservers.set(Parameter.MATERIAL_COLOR, [

package/src/api/classes/variant.ts

@@ -1,6 +1,5 @@
 import { deactivateTransformNode, getDottedPathForNode, injectNodeMetadata } from '../util/babylonHelper';
 import { loadJson, mergeMaps } from '../util/resourceHelper';
-import { createMaterialFromCbnAssets } from '../util/sceneLoaderHelper';
 import { DottedPath } from './dottedPath';
 import { Element } from './element';
 import { Event } from './event';
@@ -421,31 +420,6 @@ export class Variant extends Parameterizable {
     return element.getMesh(meshDottedPath);
   }
 
-  /**
-   * Gets the Material defined in one of the variants glTFs by its id.
-   */
-  public getOrCreateMaterial(id: string): Material {
-    const scene = this.viewer.scene;
-
-    for (const material of this.inheritedMaterials) {
-      if (material.id === id) {
-        return material;
-      }
-    }
-    // fallback to dynamically created materials on scene
-    for (const material of scene.materials) {
-      if (material.id === id) {
-        return material;
-      }
-    }
-    const cbnAssetMaterial = createMaterialFromCbnAssets(id, scene);
-    if (cbnAssetMaterial) {
-      return cbnAssetMaterial;
-    }
-
-    throw new Error(`Material with id "${id}" does not exist for variant "${this.id}".`);
-  }
-
   /**
    * Creates a living clone of this {@link Variant}. Will clone all parent {@link Variant}s in tree.
    *

package/src/api/classes/viewer.ts

@@ -8,6 +8,7 @@ import { SpecStorage } from '../store/specStorage';
 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 { AnimationInterface } from './animationInterface';
 import { Event } from './event';
@@ -79,6 +80,10 @@ export class Viewer extends EventBroadcaster {
    * This data is most likely coming from babylon assets from the Combeenation system but other sources are also valid.
    */
   public static generateSpec(genData: SpecGenerationData[]): StructureJson {
+    // dots in the variant name indicate inheritance, but this should not be the case for an auto-generated spec
+    // therefore dots are exchanged with slashes
+    const safeGenData: SpecGenerationData[] = genData.map(data => ({ ...data, name: replaceDots(data.name) }));
+
     const spec: StructureJson = {
       // common scene settings as suggested in the viewer docs
       scene: {
@@ -98,7 +103,7 @@ export class Viewer extends EventBroadcaster {
         // create one instance for each input entry
         // name and variant are named accordingly from the input, instance will be hidden by default and lazy loading
         // is activated
-        instances: genData.map(instanceData => ({
+        instances: safeGenData.map(instanceData => ({
           name: instanceData.name,
           variant: instanceData.name,
           lazy: true,
@@ -110,7 +115,7 @@ export class Viewer extends EventBroadcaster {
       // variants definition is also mapped to the input array, using the name as key and url as glTF source
       // no elements are created here, since this should be done automatically from the system
       // => create one element which contains all root nodes of the imported 3d file (GLB or Babylon)
-      variants: genData.reduce((accVariants, curVariant) => {
+      variants: safeGenData.reduce((accVariants, curVariant) => {
         accVariants[curVariant.name] = {
           glTF: curVariant.url,
         };

package/src/api/internal/sceneSetup.ts

@@ -121,7 +121,7 @@ const sceneSetup = async function (engine: Engine, sceneJson: SceneJson): Promis
     cameras.push(camera);
   }
   // grounds
-  const groundDefinitions = get(sceneJson.scene, 'grounds') as GroundDefinitions;
+  const groundDefinitions = get(sceneJson.scene, 'grounds', {}) as GroundDefinitions;
   if (!isEmpty(groundDefinitions)) {
     for (const groundName in groundDefinitions) {
       await processGround(scene, groundName, groundDefinitions[groundName]);

package/src/api/util/babylonHelper.ts

@@ -1,6 +1,10 @@
 import { DottedPath } from '../classes/dottedPath';
 import { defaultEnvHelperColor, defaultSceneClearColor } from '../internal/sceneSetup';
-import { addMissingMaterialObserver, missingMaterialMetadataName } from './sceneLoaderHelper';
+import {
+  addMissingMaterialObserver,
+  createMaterialFromCbnAssets,
+  missingMaterialMetadataName,
+} from './sceneLoaderHelper';
 import { EnvironmentHelper } from '@babylonjs/core/Helpers/environmentHelper';
 import { PhotoDome } from '@babylonjs/core/Helpers/photoDome';
 import { HighlightLayer } from '@babylonjs/core/Layers/highlightLayer';
@@ -27,6 +31,7 @@ import { cloneDeep, get, has, merge } from 'lodash-es';
 
 const backgroundDomeName = 'BackgroundDome_ViewerGenerated';
 const envHelperMetadataName = 'viewerEnvHelper';
+const materialWaitingToBeSetMetadataName = 'materialWaitingToBeSet';
 
 /**
  * @param node
@@ -354,32 +359,101 @@ const changeEnvironment = function (scene: Scene, envDef: EnvironmentDefinition)
 };
 
 /**
- * @param node
- * @param materialName
- * @param deep
+ * Sets a material by a given material id as material property on the given node.
+ *
+ * If the material is not already available in the scene, the viewer tries to create a material based on a Combeenation
+ * [material asset](https://docs.combeenation.com/docs/howto-create-and-use-babylon-and-material-asset).
+ * This of course only works if the viewer is used inside a Combeenation configurator.
+ *
+ * Furthermore this function also defers the material creation if the node is not visible yet to improve network &
+ * viewer bootstrap performance as textures are automatically being lazy loaded only when they are actually visible in
+ * the scene.
+ *
+ * Finally the material will not be applied before all its textures have been loaded. In this way "flickering" effects
+ * will be avoided, since the material would be incomplete without its loaded textures.
  */
-const setMaterial = function (variant: Variant, node: TransformNode, materialName: string, deep: boolean = true) {
+const setMaterial = function (
+  scene: Scene,
+  node: TransformNode,
+  materialId: string,
+  deep: boolean = true,
+  variant?: Variant
+) {
   if (node instanceof AbstractMesh) {
-    const materialExists = variant.viewer.scene.getMaterialById(materialName);
+    const materialExists = scene.getMaterialById(materialId);
     const hasMissingMaterial = has(node.metadata, missingMaterialMetadataName);
     const deferMaterialCreation = !materialExists && !node.isEnabled();
-
     if (deferMaterialCreation) {
-      injectNodeMetadata(node, { [missingMaterialMetadataName]: materialName }, false);
-
-      // If it already had the missing material flag before, there already exists an observer...
+      // do not set the material
+      injectNodeMetadata(node, { [missingMaterialMetadataName]: materialId }, false);
+      // if it already had the missing material flag before, there already exists an observer...
       if (!hasMissingMaterial) {
         addMissingMaterialObserver(node);
       }
     } else {
-      node.material = variant.getOrCreateMaterial(materialName);
+      // create material an apply it when textures have been loaded
+      const material = getOrCreateMaterial(scene, materialId, variant);
+      applyMaterialAfterTexturesLoaded(material, node);
+
       if (hasMissingMaterial) {
         delete node.metadata[missingMaterialMetadataName];
       }
     }
   }
+  // recursively set materials on children (if desired)
   if (deep) {
-    node.getChildTransformNodes(true).forEach(child => setMaterial(variant, child, materialName, deep));
+    for (const child of node.getChildTransformNodes(true)) {
+      setMaterial(scene, child, materialId, deep, variant);
+    }
+  }
+};
+
+/**
+ * Gets the Material either from the given {@link Variant}, the given scene or tries to create it from an Combeenation
+ * material asset when inside a Combeenation configurator.
+ */
+const getOrCreateMaterial = function (scene: Scene, materialId: string, variant?: Variant): Material {
+  let chosenMaterial: Material | undefined | null;
+  chosenMaterial = variant?.inheritedMaterials.find(mat => mat.id === materialId);
+  chosenMaterial = chosenMaterial || scene.materials.find(mat => mat.id === materialId);
+  chosenMaterial = chosenMaterial || createMaterialFromCbnAssets(materialId, scene);
+  if (chosenMaterial) {
+    return chosenMaterial as Material;
+  }
+  // reject when material was not found
+  let rejectMessage = `Material with id "${materialId}" does not exist on scene.`;
+  if (variant) {
+    rejectMessage = `Material with id "${materialId}" does not exist for variant "${variant.id}".`;
+  }
+  throw new Error(rejectMessage);
+};
+
+/**
+ * Waits until the materials textures are loaded and sets the material on the node if there is no newer "set material"
+ * request
+ */
+const applyMaterialAfterTexturesLoaded = async function (material: Material, node: AbstractMesh) {
+  // set current material id as last valid id, in this case all previously set materials on the node will be invalidated
+  injectNodeMetadata(node, { [materialWaitingToBeSetMetadataName]: material.id }, false);
+
+  const promTexturesReady = new Promise<void>(resolve =>
+    BaseTexture.WhenAllReady(material.getActiveTextures(), resolve)
+  );
+  // this promise should only take some time on the first call of the corresponding shader (eg: PBRMaterial shader)
+  // on each other call of the same material/shader type there should be not be a waiting time, or at maximum one frame
+  // https://forum.babylonjs.com/t/mesh-flickering-when-setting-material-initially/37312
+  const promMaterialCompiled = material.forceCompilationAsync(node);
+
+  // material needs to fulfill 2 criterias before it's ready to use
+  // - textures need to be "ready" => downloaded
+  // - dedicated shader needs to be compiled
+  // if this would not be the case you can see some "flickering" when setting the material
+  await Promise.all([promTexturesReady, promMaterialCompiled]);
+
+  // textures ready, now check if the material is still up-to-date
+  if (material.id === node.metadata[materialWaitingToBeSetMetadataName]) {
+    node.material = material;
+    delete node.metadata[materialWaitingToBeSetMetadataName];
   }
 };
 
@@ -638,6 +712,8 @@ export {
   cloneTransformNode,
   cloneNodeWithParents,
   cloneTransformNodeMaterial,
+  getOrCreateMaterial,
+  applyMaterialAfterTexturesLoaded,
   injectNodeMetadata,
   assertTransformNode,
   activateTransformNode,

package/src/api/util/sceneLoaderHelper.ts

@@ -1,7 +1,8 @@
-import { injectNodeMetadata } from './babylonHelper';
+import { applyMaterialAfterTexturesLoaded, getOrCreateMaterial, injectNodeMetadata } from './babylonHelper';
 import { ISceneLoaderPlugin } from '@babylonjs/core/Loading/sceneLoader';
 import { Material } from '@babylonjs/core/Materials/material';
 import { InstancedMesh } from '@babylonjs/core/Meshes/instancedMesh';
+import { Observer } from '@babylonjs/core/Misc/observable';
 import { AssetContainer } from '@babylonjs/core/assetContainer';
 //! overload DOM API Node due to name-clash with BJS
 import { Node as BjsNode } from '@babylonjs/core/node';
@@ -9,6 +10,11 @@ import { Scene } from '@babylonjs/core/scene';
 import { Nullable } from '@babylonjs/core/types';
 import has from 'lodash-es/has';
 
+// map for keeping track of active "node enable" observers
+const enableObserverMap: {
+  [concerningNodeId: string]: { currNodeId: string; observer: Nullable<Observer<boolean>> }[];
+} = {};
+
 export const missingMaterialMetadataName = 'missingMaterial';
 
 /**
@@ -41,23 +47,37 @@ export const getCustomCbnBabylonLoaderPlugin = function (previousLoaderPlugin: I
 /**
  * Return an observer to be applied to meshes in order to post-load missing materials
  * upon set enabled/visible.
- * @param targetMeshOrInstance AbstractMesh the observer will be applied to
+ *
  * @param concerningMesh Mesh to look for missing materials on, and create/apply to (when found).
  * @returns observer
  */
-export const getMaterialPostLoadObserver = function (targetMeshOrInstance: AbstractMesh, concerningMesh: Mesh) {
-  return (eventData: any, eventState: any) => {
+export const getMaterialPostLoadObserver = function (concerningMesh: Mesh) {
+  return async () => {
+    const scene = concerningMesh.getScene();
+
+    // can't check `isEnabled` immediatly, since the enabled state of parents and childs is not synced yet
+    // postpone to "when scene ready" to ensure a correct parent-child enable relation
+    await scene.whenReadyAsync();
+
     const hasBeenEnabled = concerningMesh.isEnabled(true);
     const materialMissing = has(concerningMesh.metadata, missingMaterialMetadataName);
     if (!hasBeenEnabled || !materialMissing) return;
     // get id of missing material
     const missingMatId = concerningMesh.metadata[missingMaterialMetadataName];
-    // try to find material on the scene
-    const existingMat = concerningMesh.getScene().getMaterialById(missingMatId);
-    // assign either existing material or freshly created one
-    concerningMesh.material = existingMat || createMaterialFromCbnAssets(missingMatId, concerningMesh.getScene());
+    // get material and apply it on the concerning mesh after all textures have been loaded
+    const material = getOrCreateMaterial(concerningMesh.getScene(), missingMatId);
+    applyMaterialAfterTexturesLoaded(material, concerningMesh);
     // since the material is there now, we do not need the related metadata tag anymore
     delete concerningMesh.metadata[missingMaterialMetadataName];
+
+    // remove all "enable" observers that were assigned to the concerning mesh
+    // the mesh got visible and therefore the observers are not needed anymore
+    enableObserverMap[concerningMesh.id].forEach(entry => {
+      const currNode = scene.getMeshById(entry.currNodeId);
+      currNode?.onEnabledStateChangedObservable.remove(entry.observer);
+    });
+    // also remove from the local observer map
+    delete enableObserverMap[concerningMesh.id];
   };
 };
 
@@ -99,30 +119,23 @@ export const addMissingMaterialObserver = function (node: BjsNode) {
   // for each of our AbstractMeshes, set an observer on the AbstractMesh itself and all of its parents.
   let currNode: Nullable<BjsNode> = node;
   while (currNode) {
-    // Note HAR: Using `addOnce` could be wrong in certain situations.
-    // E.g.:
-    //   * 2 meshes `parentMesh` & `parentMesh.concerningMesh`
-    //   * `concerningMesh` is having the missing material flag
-    //   * Both `parentMesh` & `concerningMesh` are disabled
-    //   * `parentMesh` is enabled -> material should **not** be created as `concerningMesh` is still disabled
-    //   * `parentMesh` is disabled
-    //   * `concerningMesh` is enabled -> material should **not** be created as `concerningMesh` is still invisible
-    //     because its `parentMesh` is ATM disabled
-    //   * `parentMesh` & `concerningMesh` are both enable
-    //     -> material should be created as `concerningMesh` is now actually visible but it isn't, as all observers were
-    //        only fired once 🔥
-    //
-    // However: Using `add` instead of `addOnce` requires rather complicated manual clean up work...
+    const callback = getMaterialPostLoadObserver(concerningNode);
+    const observer = currNode.onEnabledStateChangedObservable.add(callback);
+
+    // store the observer in a local map to keep track of the active "enable" observers
+    // observers will be removed when the concerning node gets enabled
+    if (!enableObserverMap[concerningNode.id]) {
+      enableObserverMap[concerningNode.id] = [];
+    }
+    enableObserverMap[concerningNode.id].push({ currNodeId: currNode.id, observer });
 
-    // add observer. needed only once per node, hence addOnce()
-    node.onEnabledStateChangedObservable.addOnce(getMaterialPostLoadObserver(currNode as AbstractMesh, concerningNode));
-    // console.log('## observer set on: ' + meshOrInstance.name);
     currNode = currNode.parent;
   }
 };
 
 /**
  * Look up the provided materials (see library import) and create and return one if found.
+ *
  * @param materialId BabylonJs material-id. E.g. 'concrete".
  * @param scene BabylonJs scene
  * @returns PBRMaterial | null

package/src/api/util/stringHelper.ts

@@ -20,4 +20,11 @@ const camelToSnakeCase = function (str: string): string {
     .toLowerCase();
 };
 
-export { uuidv4, camelToSnakeCase };
+/**
+ * Replaces all dots from the input string with a desired character ('/' by default)
+ */
+const replaceDots = function (str: string, replaceChar = '/'): string {
+  return str.split('.').join(replaceChar);
+};
+
+export { uuidv4, camelToSnakeCase, replaceDots };

package/src/dev.ts

@@ -12,12 +12,10 @@ import { set } from 'lodash-es';
 const loadingElement = document.getElementById('loading') as HTMLDivElement;
 
 Emitter.on(Event.BOOTSTRAP_START, () => {
-  Emitter.on(Event.LOADING_START, () => {
-    loadingElement!.style.display = 'block';
-  });
-  Emitter.on(Event.VARIANT_CREATED, () => {
-    loadingElement!.style.display = 'none';
-  });
+  loadingElement!.style.display = 'block';
+});
+Emitter.on(Event.BOOTSTRAP_END, () => {
+  loadingElement!.style.display = 'none';
 });
 
 document.addEventListener('DOMContentLoaded', main);
@@ -25,6 +23,7 @@ document.addEventListener('DOMContentLoaded', main);
 window.Cbn = {
   Assets: {
     getMaterial(materialId: string) {
+      //! this creates a new function on the object that uses the imported function of the same name..
       const material = getMaterial(materialId);
       if (material) return material;