@combeenation/3d-viewer 17.1.0 → 18.0.0-beta2

package/src/manager/model-manager.ts

@@ -1,33 +1,17 @@
 import {
   AssetContainer,
-  BuiltInParameter,
   DecalConfiguration,
   MaterialManager,
   MeshBuilder,
-  ParameterManager,
-  SceneLoader,
   TransformNode,
   Viewer,
   ViewerError,
   ViewerErrorIds,
 } from '../index';
+import { BaseAsset, loadAsset, prepareAssetForScene } from '../internal/asset-helper';
 import { cloneModelAssetContainer } from '../internal/cloning-helper';
-import { getInternalMetadataValue } from '../internal/metadata-helper';
 import { isArray } from 'lodash-es';
 
-/**
- * Contains cbn custom data, like decals.
- * This is just a temporary type, as the `loadAssetContainer` function only returns an asset container, which can be
- * altered by our file loader plugin.
- * After loading the model, `cbnData` is cropped and a pure asset container is available for further processing.
- *
- * @internal
- */
-export class ExtendedAssetContainer extends AssetContainer {
-  cbnData?: CbnBabylonFileData;
-}
-
-type CbnBabylonFileData = { decals?: ParsedDecalConfiguration[] };
 export type ParsedDecalConfiguration = DecalConfiguration & { materialId?: string; tags?: string };
 
 export type ModelAssetDefinition = {
@@ -62,20 +46,14 @@ export type ModelCloneOptions = {
   tagNamingStrategy?: TagNamingStrategy;
 };
 
-type Model = {
-  name: string;
-  url: string;
-  state: ModelAssetState;
-  assetContainer: AssetContainer;
-  cbnBabylonFileData?: CbnBabylonFileData;
+type ModelAsset = BaseAsset & {
+  decals?: ParsedDecalConfiguration[];
   isClone: boolean;
   // only set for "instantiated" clones
   sourceModelName?: string;
   visibilityCallId?: number;
 };
 
-type ModelAssetState = 'notLoaded' | 'loading' | 'loaded' | 'inScene';
-
 /**
  * Manager for handling 3d models.\
  * Responsible for loading models and handling their visibility.\
@@ -84,12 +62,11 @@ type ModelAssetState = 'notLoaded' | 'loading' | 'loaded' | 'inScene';
 export class ModelManager {
   /**
    * CAUTION: this has to be in sync with the Combeenation backend!
-   * @internal
    */
   public static readonly CBN_FALLBACK_MODEL_ASSET_NAME = '$fallback';
 
-  protected _modelAssets: { [name: string]: Model } = {};
-  protected _fallbackModelAsset: Model = {
+  protected _modelAssets: { [name: string]: ModelAsset } = {};
+  protected _fallbackModelAsset: ModelAsset = {
     name: ModelManager.CBN_FALLBACK_MODEL_ASSET_NAME,
     url: '',
     state: 'loaded',
@@ -113,6 +90,7 @@ export class ModelManager {
     return inputStr.split('/').join('.');
   }
 
+  /** @internal */
   public constructor(protected viewer: Viewer) {}
 
   /**
@@ -144,11 +122,11 @@ export class ModelManager {
     for (const { name, url } of modelAssets) {
       const existingModel = this._modelAssets[name];
       if (existingModel) {
-        console.warn(`Model ${name} is already registered`);
+        console.warn(`Model "${name}" is already registered`);
         return;
       }
 
-      const model: Model = { name, url, state: 'notLoaded', assetContainer: new AssetContainer(), isClone: false };
+      const model: ModelAsset = { name, url, state: 'notLoaded', assetContainer: new AssetContainer(), isClone: false };
       this._modelAssets[name] = model;
     }
   }
@@ -170,7 +148,7 @@ export class ModelManager {
     }
 
     if (model.state !== 'notLoaded') {
-      console.warn(`Model ${name} is already loaded or currently loading`);
+      console.warn(`Model "${name}" is already loaded or currently loading`);
       return;
     }
 
@@ -187,14 +165,14 @@ export class ModelManager {
   public async setModelVisibility(
     modelVisibility: ModelVisibilityEntry | ModelVisibilityEntry[]
   ): Promise<ModelVisibilityEntry[]> {
-    const showModels: Model[] = [];
-    const hideModels: Model[] = [];
+    const modelsToShow: ModelAsset[] = [];
+    const modelsToHide: ModelAsset[] = [];
 
     if (!isArray(modelVisibility)) {
       modelVisibility = [modelVisibility];
     }
 
-    for (const entry of modelVisibility) {
+    const loadModelProms = modelVisibility.map(async entry => {
       const model = this._getModel(entry.name);
       if (!model) {
         throw new ViewerError({
@@ -206,8 +184,10 @@ export class ModelManager {
       // there can be multiple "setModelVisibility" calls while the model is loading
       // loading can be awaited, but it has to be ensured, that the last call of "setModelVisibility" has priority
       // therefore we store the id of the call in the model
-      const curVisibilityCallId = (model.visibilityCallId ?? 0) + 1;
-      model.visibilityCallId = curVisibilityCallId;
+      model.visibilityCallId = (model.visibilityCallId ?? 0) + 1;
+      const curVisibilityCallId = model.visibilityCallId;
+      let showModel = false;
+      let hideModel = false;
 
       if (entry.visible) {
         if (model.state === 'notLoaded') {
@@ -215,45 +195,51 @@ export class ModelManager {
 
           // check if this is still the latest visibility call
           if (model.visibilityCallId === curVisibilityCallId) {
-            showModels.push(model);
+            showModel = true;
           }
         } else if (model.state === 'loading') {
           await this._loadModelPromises[model.name];
 
           if (model.visibilityCallId === curVisibilityCallId) {
-            showModels.push(model);
+            showModel = true;
           }
         } else if (model.state === 'loaded') {
-          showModels.push(model);
+          showModel = true;
         }
       } else {
         if (model.state === 'loading') {
           await this._loadModelPromises[model.name];
 
           if (model.visibilityCallId === curVisibilityCallId) {
-            hideModels.push(model);
+            hideModel = true;
           }
         } else if (model.state === 'inScene') {
-          hideModels.push(model);
+          hideModel = true;
         }
       }
-    }
-
-    for (const showModel of showModels) {
-      await this._prepareModelForScene(showModel);
-    }
 
-    for (const showModel of showModels) {
-      await this._showModel(showModel, true);
-    }
-
-    for (const hideModel of hideModels) {
-      this._hideModel(hideModel);
-    }
+      if (showModel) {
+        await this._prepareModelForScene(model);
+        modelsToShow.push(model);
+      } else if (hideModel) {
+        modelsToHide.push(model);
+      }
+    });
+    // model loading and preparation (e.g. create materials) is done simultaniously for all models to save time
+    // model (`ModelManager._loadModelPromises`) and material queues (`MaterialManager._createMaterialPromises`) are
+    // responsible for correct loading state handling of these instances
+    await Promise.all(loadModelProms);
 
     const returnVal: ModelVisibilityEntry[] = [];
-    showModels.forEach(showModel => returnVal.push({ name: showModel.name, visible: true }));
-    hideModels.forEach(hideModel => returnVal.push({ name: hideModel.name, visible: false }));
+    modelsToShow.forEach(model => {
+      // show model is not async, as preparation has already been done
+      this._showModel(model, true);
+      returnVal.push({ name: model.name, visible: true });
+    });
+    modelsToHide.forEach(model => {
+      this._hideModel(model);
+      returnVal.push({ name: model.name, visible: false });
+    });
 
     return returnVal;
   }
@@ -294,7 +280,7 @@ export class ModelManager {
       await this._loadModelPromises[sourceModel.name];
     }
 
-    const clonedModel: Model = {
+    const clonedModel: ModelAsset = {
       name: newModelName,
       url: sourceModel.url,
       state: 'loaded',
@@ -400,14 +386,14 @@ export class ModelManager {
       await this._prepareModelForScene(model);
     }
 
-    return model.cbnBabylonFileData?.decals ?? [];
+    return model.decals ?? [];
   }
 
   /**
    * Get model by name
    */
-  protected _getModel(name: string): Model | undefined {
-    if (name === '$fallback') {
+  protected _getModel(name: string): ModelAsset | undefined {
+    if (name === ModelManager.CBN_FALLBACK_MODEL_ASSET_NAME) {
       return this._fallbackModelAsset;
     }
 
@@ -420,67 +406,16 @@ export class ModelManager {
   /**
    * Load model into scene, but don't show it immediately
    */
-  protected async _loadModel(model: Model): Promise<void> {
+  protected async _loadModel(model: ModelAsset): Promise<void> {
     const loadModelPromise = async (): Promise<void> => {
-      model.state = 'loading';
-      const curEnvTexture = this.viewer.scene.environmentTexture;
-      const curEnvIntensity = this.viewer.scene.environmentIntensity;
-
-      // CB-9240: Babylon.js doesn't recognize gzipped babylon files (`.babylon.gz`) as such, leading to a warning
-      // message, therefore we overwrite the plugin extension actively for such files
-      let pluginExtension;
-      try {
-        // URL constructor can throw for "valid" URL, which happened to be the case for the test asset environment where
-        // the urls are relative (starting with ".")
-        const urlObj = new URL(model.url);
-        if (urlObj.pathname.endsWith('.babylon.gz')) {
-          pluginExtension = '.babylon';
-        }
-      } catch (e) {}
-
-      let assetContainer;
-      try {
-        const fullContainer = (await SceneLoader.LoadAssetContainerAsync(
-          '',
-          model.url,
-          this.viewer.scene,
-          undefined,
-          pluginExtension
-        )) as ExtendedAssetContainer;
-
-        // crop and store custom cbn data from .babylon file
-        model.cbnBabylonFileData = fullContainer.cbnData;
-        delete fullContainer.cbnData;
-
-        // from here it's a basic asset container again
-        assetContainer = fullContainer as AssetContainer;
-      } catch (e) {
-        throw new ViewerError({
-          id: ViewerErrorIds.AssetLoadingFailed,
-          message: (e as Error).message,
-        });
-      }
+      const { cbnData } = await loadAsset(model, this.viewer);
+
+      model.decals = cbnData?.decals;
 
       // remove all lights and cameras from the asset, as this data should be handled globally in the scene instead of
       // being in a model context
-      [...assetContainer.lights].forEach(light => light.dispose());
-      [...assetContainer.cameras].forEach(camera => camera.dispose());
-
-      // materials should be a "global" thing and not assigned to an asset container
-      // this is not relevant in most of the cases, since materials are cropped from babylon models on the CBN server
-      // anyway
-      assetContainer.materials.forEach(material => {
-        this.viewer.scene.addMaterial(material);
-        material._parentContainer = null;
-      });
-      assetContainer.materials = [];
-
-      // environment texture and intensity has been overwritten by load asset container function
-      this.viewer.scene.environmentTexture = curEnvTexture;
-      this.viewer.scene.environmentIntensity = curEnvIntensity;
-
-      model.assetContainer = assetContainer;
-      model.state = 'loaded';
+      [...model.assetContainer.lights].forEach(light => light.dispose());
+      [...model.assetContainer.cameras].forEach(camera => camera.dispose());
 
       delete this._loadModelPromises[model.name];
     };
@@ -494,7 +429,7 @@ export class ModelManager {
    * This is typically done before the model is added to the scene to avoid changes on the visible model, which ensures
    * a smooth model switch behaviour.
    */
-  protected async _prepareModelForScene(model: Model): Promise<void> {
+  protected async _prepareModelForScene(model: ModelAsset): Promise<void> {
     if (model.sourceModelName) {
       // source model has to be prepared for scene as well in "instantiate" mode, because materials would not be
       // loaded otherwise
@@ -504,10 +439,7 @@ export class ModelManager {
       await this._prepareModelForScene(sourceModel);
     }
 
-    await this.viewer.parameterManager.applyAllParameterValuesToModel(model.assetContainer);
-    // parameter manager did his job, now apply the deferred materials to all meshes that are not explicitely hidden by
-    // the parameter manager
-    await this._applyDeferredMaterialsForAllVisibleMeshes(model);
+    await prepareAssetForScene(model, this.viewer);
   }
 
   /**
@@ -517,7 +449,7 @@ export class ModelManager {
    * @param skipPreparation optionally skip applying parameter values to model before showing it
    *                        (see {@link _prepareModelForScene})
    */
-  protected async _showModel(model: Model, skipPreparation?: boolean): Promise<void> {
+  protected async _showModel(model: ModelAsset, skipPreparation?: boolean): Promise<void> {
     if (!skipPreparation) {
       await this._prepareModelForScene(model);
     }
@@ -529,23 +461,8 @@ export class ModelManager {
   /**
    * Remove assets of asset container from scene
    */
-  protected _hideModel(model: Model): void {
+  protected _hideModel(model: ModelAsset): void {
     model.assetContainer.removeFromScene();
     model.state = 'loaded';
   }
-
-  /**
-   * Creates and assigns each "deferred" material to the corresponding mesh, if the mesh is visible.
-   * Model should be ready to use immediately after this function has done it's job.
-   */
-  protected async _applyDeferredMaterialsForAllVisibleMeshes(model: Model): Promise<void> {
-    for (const mesh of model.assetContainer.meshes) {
-      const deferredMaterial = getInternalMetadataValue(mesh, 'deferredMaterial');
-      const rawVisibleValue = this.viewer.parameterManager.getParameterValueOfNode(mesh, BuiltInParameter.Visible);
-      const visible = rawVisibleValue === undefined || ParameterManager.parseBoolean(rawVisibleValue) === true;
-      if (deferredMaterial && visible) {
-        await this.viewer.materialManager.setMaterialOnMesh(deferredMaterial as string, mesh);
-      }
-    }
-  }
 }

package/src/manager/parameter-manager.ts

@@ -97,7 +97,7 @@ export type ParameterObserver = (payload: ParameterObserverPayload) => Promise<v
 
 /**
  * Payload of parameter observer.\
- * Contains current data of parameter entry, which can be usefull for implementing the dedicated observer
+ * Contains current data of parameter entry, which can be useful for implementing the dedicated observer
  */
 export type ParameterObserverPayload = {
   subject: ParameterSubject;
@@ -258,6 +258,7 @@ export class ParameterManager {
   protected _parameterEntries: ParameterEntry[] = [];
   protected _parameterObserver: { [parameterName: ParameterName]: ParameterObserver } = {};
 
+  /** @internal */
   public constructor(protected viewer: Viewer) {
     this._addBuiltInParameterObservers();
   }
@@ -459,49 +460,28 @@ export class ParameterManager {
   }
 
   /**
-   * @returns Desired parameter value of a certain node.
-   * Tags are considered as well but have lower priority than node parameters, as these are more specific.
-   *
-   * @internal
-   */
-  public getParameterValueOfNode(node: TransformNode, parameterName: string): ParameterValue | undefined {
-    const nodeParamValue = this.getParameterValue({ nodeName: node.name }, parameterName);
-    if (nodeParamValue !== undefined) {
-      return nodeParamValue;
-    }
-
-    const tags = getTagsAsStrArr(node);
-    const tagParamValue = tags.reduce<ParameterValue | undefined>((accValue, curTag) => {
-      // NOTE: it is possible that values are available for multiple tags
-      // in this case the resulting parameter value is quite "random" as the last tag in the tag string of the node has
-      // priority
-      const tagParamValue = this.getParameterValue({ tagName: curTag }, parameterName);
-      return accValue ?? tagParamValue;
-    }, undefined);
-
-    return tagParamValue;
-  }
-
-  /**
-   * @returns Desired parameter value of a certain material.
-   * Tags are considered as well but have lower priority than material parameters, as these are more specific.
-   * Unused ATM, but added for consistency as counter part for {@link getParameterValueOfNode}
+   * Retrieves visibility state of node, considering pending parameter values and node hierarchy.\
+   * `node.isEnabled()` alone is insufficient here, as visibility observers for the desired node or one of it's parents
+   * may be called in the same cycle, overwriting the visibility state again.
    *
    * @internal
    */
-  public getParameterValueOfMaterial(material: Material, parameterName: string): ParameterValue | undefined {
-    const materialParamValue = this.getParameterValue({ materialName: material.name }, parameterName);
-    if (materialParamValue !== undefined) {
-      return materialParamValue;
+  public getNestedVisibilityParameterValueOfNode(node: TransformNode): boolean {
+    let curNode: TransformNode | null = node;
+    let visibleByParameter: boolean | undefined = undefined;
+    while (curNode && visibleByParameter !== false) {
+      const curNodeVisibleByParameter = this._getParameterValueOfNode(curNode, BuiltInParameter.Visible);
+      if (curNodeVisibleByParameter !== undefined) {
+        visibleByParameter = curNodeVisibleByParameter as boolean;
+      }
+      curNode = curNode.parent as TransformNode;
     }
 
-    const tags = getTagsAsStrArr(material);
-    const tagParamValue = tags.reduce<ParameterValue | undefined>((accValue, curTag) => {
-      const tagParamValue = this.getParameterValue({ tagName: curTag }, parameterName);
-      return accValue ?? tagParamValue;
-    }, undefined);
+    // check state of nested visibility parameter value and fall back to basic node enabled state
+    const visible =
+      visibleByParameter !== undefined ? ParameterManager.parseBoolean(visibleByParameter) : node.isEnabled();
 
-    return tagParamValue;
+    return visible;
   }
 
   /**
@@ -511,33 +491,40 @@ export class ParameterManager {
     this.setParameterObserver(BuiltInParameter.Visible, async ({ nodes, newValue }) => {
       const visible = ParameterManager.parseBoolean(newValue);
 
-      for (const node of nodes) {
-        if (visible) {
+      const observerProms = nodes.map(async node => {
+        const visibleNested = this.getNestedVisibilityParameterValueOfNode(node);
+        if (visibleNested) {
           // if a mesh gets visible by this operation we have to activate the assigned material which is stored in the
           // internal metadata
           // => consider child meshes as well (CB-10143)
           const activatedNodes = [node, ...node.getChildMeshes(false)];
-          for (const activatedNode of activatedNodes) {
-            const deferredMaterial = getInternalMetadataValue(activatedNode, 'deferredMaterial');
-            if (deferredMaterial) {
+          const setMaterialProms = activatedNodes.map(async an => {
+            const anVisibleNested = this.getNestedVisibilityParameterValueOfNode(an);
+            const anDeferredMaterial = getInternalMetadataValue(an, 'deferredMaterial');
+            // skip applying material if it's already set via the parameter
+            const anMaterialParamValue = this._getParameterValueOfNode(an, BuiltInParameter.Material) as
+              | string
+              | undefined;
+            if (anVisibleNested && anDeferredMaterial && !anMaterialParamValue) {
               await this.viewer.materialManager.setMaterialOnMesh(
-                deferredMaterial as string,
+                anDeferredMaterial,
                 // this cast is fine, as deferred material can only be set on meshes
-                activatedNode as AbstractMesh
+                an as AbstractMesh
               );
             }
-          }
-
-          node.setEnabled(true);
-        } else {
-          node.setEnabled(false);
+          });
+          await Promise.all(setMaterialProms);
         }
-      }
+
+        // set enabled state anyway
+        node.setEnabled(visible);
+      });
+      await Promise.all(observerProms);
     });
     this.setParameterObserver(BuiltInParameter.Material, async ({ nodes, newValue }) => {
       const material = ParameterManager.parseString(newValue);
 
-      for (const node of nodes) {
+      const observerProms = nodes.map(async node => {
         if (!(node instanceof AbstractMesh)) {
           throw new ViewerError({
             id: ViewerErrorIds.InvalidParameterSubject,
@@ -545,28 +532,15 @@ export class ParameterManager {
           });
         }
 
-        // NOTE: don't use node.isEnabled() as visibility observer is probably called in same cycle but later
-        // however the parameter value is already correct at this stage
-        // we have to go through all parents as well, because a parent may have been set to false, which also disables
-        // this child node
-        let curNode: TransformNode | null = node;
-        let visibleByParameter: boolean | undefined = undefined;
-        while (curNode && visibleByParameter !== false) {
-          const curNodeVisibleByParameter = this.getParameterValueOfNode(curNode, BuiltInParameter.Visible);
-          if (curNodeVisibleByParameter !== undefined) {
-            visibleByParameter = curNodeVisibleByParameter as boolean;
-          }
-          curNode = curNode.parent as TransformNode;
-        }
-
-        const visible =
-          visibleByParameter !== undefined ? ParameterManager.parseBoolean(visibleByParameter) : node.isEnabled();
+        // only set material if the mesh is visible, or gets visible by the parameter update
+        const visible = this.getNestedVisibilityParameterValueOfNode(node);
         if (visible) {
           await this.viewer.materialManager.setMaterialOnMesh(material, node);
         } else {
           setInternalMetadataValue(node, 'deferredMaterial', material);
         }
-      }
+      });
+      await Promise.all(observerProms);
     });
     this.setParameterObserver(BuiltInParameter.Position, async ({ nodes, newValue }) => {
       const position = ParameterManager.parseVector(newValue);
@@ -710,12 +684,15 @@ export class ParameterManager {
     const tagParamEntries = parameterEntries.filter(entry => isTagParameterSubject(entry.subject));
     const nonTagParamEntries = parameterEntries.filter(entry => !isTagParameterSubject(entry.subject));
 
-    for (const entry of tagParamEntries) {
-      await this._applyParameterValue(entry.subject, entry.parameterName, assetContainer);
-    }
-    for (const entry of nonTagParamEntries) {
-      await this._applyParameterValue(entry.subject, entry.parameterName, assetContainer);
-    }
+    const tagParamProms = tagParamEntries.map(entry =>
+      this._applyParameterValue(entry.subject, entry.parameterName, assetContainer)
+    );
+    await Promise.all(tagParamProms);
+
+    const nonTagParamProms = nonTagParamEntries.map(entry =>
+      this._applyParameterValue(entry.subject, entry.parameterName, assetContainer)
+    );
+    await Promise.all(nonTagParamProms);
   }
 
   /**
@@ -811,4 +788,46 @@ export class ParameterManager {
 
     return entries;
   }
+
+  /**
+   * @returns Desired parameter value of a certain node.\
+   * Tags are considered as well but have lower priority than node parameters, as these are more specific.
+   */
+  protected _getParameterValueOfNode(node: TransformNode, parameterName: string): ParameterValue | undefined {
+    const nodeParamValue = this.getParameterValue({ nodeName: node.name }, parameterName);
+    if (nodeParamValue !== undefined) {
+      return nodeParamValue;
+    }
+
+    const tags = getTagsAsStrArr(node);
+    const tagParamValue = tags.reduce<ParameterValue | undefined>((accValue, curTag) => {
+      // NOTE: it is possible that values are available for multiple tags
+      // in this case the resulting parameter value is quite "random" as the last tag in the tag string of the node has
+      // priority
+      const tagParamValue = this.getParameterValue({ tagName: curTag }, parameterName);
+      return accValue ?? tagParamValue;
+    }, undefined);
+
+    return tagParamValue;
+  }
+
+  /**
+   * @returns Desired parameter value of a certain material.\
+   * Tags are considered as well but have lower priority than material parameters, as these are more specific.\
+   * Unused ATM, but added for consistency as counter part for {@link _getParameterValueOfNode}
+   */
+  protected _getParameterValueOfMaterial(material: Material, parameterName: string): ParameterValue | undefined {
+    const materialParamValue = this.getParameterValue({ materialName: material.name }, parameterName);
+    if (materialParamValue !== undefined) {
+      return materialParamValue;
+    }
+
+    const tags = getTagsAsStrArr(material);
+    const tagParamValue = tags.reduce<ParameterValue | undefined>((accValue, curTag) => {
+      const tagParamValue = this.getParameterValue({ tagName: curTag }, parameterName);
+      return accValue ?? tagParamValue;
+    }, undefined);
+
+    return tagParamValue;
+  }
 }