@combeenation/3d-viewer 6.2.0 → 6.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combeenation/3d-viewer",
-  "version": "6.2.0",
+  "version": "6.3.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

@@ -65,6 +65,15 @@ export class Viewer extends EventBroadcaster {
 
   static version = buildInfo.version;
 
+  // these are constants for calculating the camera settings, depending on the bounding box size of the meshes to zoom
+  // the algorithms and constant values are directly taken from the BabylonJS repository
+  private static readonly _autofocusConstants = {
+    minZ: 100,
+    wheelPrecision: 100,
+    panningSensibility: 5000,
+    pinchPrecision: 200,
+  };
+
   /**
    * Help function for automatically creating a valid Spec from a list of variant names and dedicated GLB/Babylon URLs.
    * This data is most likely coming from babylon assets from the Combeenation system but other sources are also valid.
@@ -461,12 +470,40 @@ export class Viewer extends EventBroadcaster {
     // get bounding box of all visible meshes, this is the base for the autofocus algorithm
     const boundingBox = await this.calculateBoundingBox(exclude);
 
-    // focus the helper camera and set the calculated camera data to the real camera
-    const helperCamera = this.getFocusedHelperCamera(boundingBox, settings);
-    await this.applyFocusedHelperCameraData(activeCamera, helperCamera, settings);
+    const radius = boundingBox.getBoundingInfo().boundingSphere.radius;
+    const center = boundingBox.getBoundingInfo().boundingSphere.center;
+    const diameter = radius * 2;
+
+    // set lower radius limit on edge of bounding sphere to make sure that we can't dive into the meshes
+    activeCamera.lowerRadiusLimit = radius;
 
-    // remove the helper camera
-    helperCamera.dispose();
+    // additional settings
+    // constants for division are taken directly from BabylonJS repository
+    activeCamera.minZ = Math.min(radius / Viewer._autofocusConstants.minZ, 1);
+    if (settings?.adjustWheelPrecision !== false) {
+      activeCamera.wheelPrecision = Viewer._autofocusConstants.wheelPrecision / radius;
+    }
+    if (settings?.adjustPanningSensibility !== false) {
+      activeCamera.panningSensibility = Viewer._autofocusConstants.panningSensibility / diameter;
+    }
+    if (settings?.adjustPinchPrecision !== false) {
+      activeCamera.pinchPrecision = Viewer._autofocusConstants.pinchPrecision / radius;
+    }
+
+    const radiusFactor = settings?.radiusFactor ?? 1;
+    const alpha = (settings?.alpha ?? -90) * (Math.PI / 180);
+    const beta = (settings?.beta ?? 90) * (Math.PI / 180);
+
+    const newCameraPosition = {
+      alpha: alpha,
+      beta: beta,
+      // this calculation is a bit "simplified", as it doesn't consider the viewport ratio or the frustum angle
+      // but it's also done this way in the BabylonJs repository, so it should be fine for us
+      radius: diameter * radiusFactor,
+      target: center,
+    };
+
+    await this.animationManager.animateToPlacement(activeCamera, newCameraPosition, settings?.animation);
   }
 
   /**
@@ -629,7 +666,10 @@ export class Viewer extends EventBroadcaster {
     const setupJson = SpecStorage.get<SetupJson>('setup');
     const instances: VariantInstance[] = [];
     for (const instanceDefinition of setupJson.instances) {
-      if (instanceDefinition.lazy) {
+      // 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
+      if (instanceDefinition.lazy && instanceDefinition.parameters?.visible !== true) {
         this.variantInstances.register(instanceDefinition);
         continue;
       }
@@ -643,78 +683,4 @@ export class Viewer extends EventBroadcaster {
     }
     return instances;
   }
-
-  /**
-   * Help function for focusing a helper camera exactly onto the given bounding box
-   */
-  private getFocusedHelperCamera(boundingBox: Mesh, settings?: AutofocusSettings): ArcRotateCamera {
-    // use helper camera to get some default values and set the values of the real camera accordingly
-    const helperCamera = new ArcRotateCamera(
-      '__helper_camera__',
-      0, // camera angles will be overwritten after the target has been set
-      0,
-      0, // radius will be calculated, so we can set to 0 here
-      Vector3.Zero(),
-      this.scene
-    );
-    // this is required for automatically calculating the `lowerRadiusLimit`, so that we don't "dive" into meshes
-    // see https://doc.babylonjs.com/divingDeeper/behaviors/cameraBehaviors#framing-behavior
-    helperCamera.useFramingBehavior = true;
-
-    // `minZ` is the camera distance beyond which the mesh will be clipped
-    // this should be very low, but can't be zero
-    // a good value seems to be 1% of the bounding box size (= radius), whereas the value shouldn't go above 1, which is
-    // also the default value
-    const radius = boundingBox.getBoundingInfo().boundingSphere.radius;
-    helperCamera.minZ = Math.min(radius / 100, 1);
-
-    // set desired camera data, these won't be changed by the autofocus function!
-    // default values should focus the element exactly from the front (= XY Plane)
-    helperCamera.setTarget(boundingBox, true);
-    helperCamera.alpha = (settings?.alpha ?? -90) * (Math.PI / 180);
-    helperCamera.beta = (settings?.beta ?? 90) * (Math.PI / 180);
-
-    // finally zoom to the bounding box
-    // also apply a zoom factor, this adjusts the borders around the model in the viewport
-    helperCamera.zoomOnFactor = settings?.radiusFactor || 1;
-    helperCamera.zoomOn([boundingBox], true);
-
-    return helperCamera;
-  }
-
-  /**
-   * Help function for applying the relevant data of the focused helper camera to the real camera
-   */
-  private async applyFocusedHelperCameraData(
-    activeCamera: ArcRotateCamera,
-    helperCamera: ArcRotateCamera,
-    settings?: AutofocusSettings
-  ) {
-    // limits
-    activeCamera.minZ = helperCamera.minZ;
-    activeCamera.maxZ = helperCamera.maxZ;
-    activeCamera.lowerRadiusLimit = helperCamera.lowerRadiusLimit;
-    activeCamera.upperRadiusLimit = helperCamera.upperRadiusLimit;
-
-    // additional settings
-    if (settings?.adjustWheelPrecision !== false) {
-      activeCamera.wheelPrecision = helperCamera.wheelPrecision;
-    }
-    if (settings?.adjustPanningSensibility !== false) {
-      activeCamera.panningSensibility = helperCamera.panningSensibility;
-    }
-    if (settings?.adjustPinchPrecision !== false) {
-      activeCamera.pinchPrecision = helperCamera.pinchPrecision;
-    }
-
-    // finally move the camera
-    // do this at last, so that all camera settings are already considered
-    const newCameraPosition: PlacementDefinition = {
-      alpha: helperCamera.alpha,
-      beta: helperCamera.beta,
-      radius: helperCamera.radius,
-      target: helperCamera.target,
-    };
-    await this.animationManager.animateToPlacement(activeCamera, newCameraPosition, settings?.animation);
-  }
 }

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,35 +359,91 @@ 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://doc.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 defined in the given {@link Variant}, scene or via {@link createMaterialFromCbnAssets}.
+ */
+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 = 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);
+
+  BaseTexture.WhenAllReady(material.getActiveTextures(), () => {
+    // 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];
+    }
+  });
+};
+
 /**
  * !!! Warning !!!
  * This function is not public API. Whilst it can help solving certain problems, it only works reliably in well defined
@@ -638,6 +699,8 @@ export {
   cloneTransformNode,
   cloneNodeWithParents,
   cloneTransformNodeMaterial,
+  getOrCreateMaterial,
+  applyMaterialAfterTexturesLoaded,
   injectNodeMetadata,
   assertTransformNode,
   activateTransformNode,

package/src/api/util/sceneLoaderHelper.ts

@@ -1,4 +1,4 @@
-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';
@@ -52,10 +52,9 @@ export const getMaterialPostLoadObserver = function (targetMeshOrInstance: Abstr
     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];
   };

package/src/dev.ts

@@ -25,6 +25,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;