@combeenation/3d-viewer 12.4.1 → 13.0.0

package/src/manager/materialManager.ts

@@ -0,0 +1,135 @@
+import {
+  AbstractMesh,
+  BaseTexture,
+  Material,
+  StandardMaterial,
+  Viewer,
+  ViewerError,
+  ViewerErrorIds,
+  ViewerEvent,
+} from '../index';
+import {
+  clearInternalMetadataValue,
+  getInternalMetadataValue,
+  setInternalMetadataValue,
+} from '../internal/metadataHelper';
+
+/**
+ * Manager for material related tasks
+ */
+export class MaterialManager {
+  /**
+   * CAUTION: this has to be in sync with the Combeenation backend!
+   * @internal
+   */
+  public static readonly CBN_FALLBACK_MATERIAL_NAME = '$fallback';
+
+  protected _createMaterialPromises: { [materialId: string]: Promise<Material | null> } = {};
+
+  /** @internal */
+  public constructor(protected viewer: Viewer) {}
+
+  /**
+   * Assigns material with certain id to desired mesh.\
+   * Creates the material if not already available (see {@link getOrCreateMaterial}).
+   */
+  public async setMaterialOnMesh(materialId: string, mesh: AbstractMesh): Promise<void> {
+    setInternalMetadataValue(mesh, 'materialToBeSet', materialId);
+
+    const material = await this.getOrCreateMaterial(materialId, mesh);
+
+    // there may have been later "setMaterialOnMesh" calls with faster material creation
+    // make sure to assign the latest material!
+    if (getInternalMetadataValue(mesh, 'materialToBeSet') === materialId) {
+      mesh.material = material;
+      clearInternalMetadataValue(mesh, 'materialToBeSet');
+      clearInternalMetadataValue(mesh, 'deferredMaterial');
+    }
+  }
+
+  /**
+   * Returns material with certain id if already available in the scene.\
+   * If this is not the case material is created from a
+   * "[Material asset](https://docs.combeenation.com/docs/howto-create-and-use-babylon-and-material-asset)"
+   * on the Combeenation server.\
+   * Waits until textures of material are fully loaded and shader is compiled. In this way "flickering" effects
+   * will be avoided, since the material would be incomplete without its loaded textures.
+   *
+   * @param mesh Required for shader compilation check, can be omitted if this check should not be done.\
+   * Use {@link setMaterialOnMesh} instead if the material should be applied on the mesh immediately.
+   */
+  public async getOrCreateMaterial(materialId: string, mesh?: AbstractMesh): Promise<Material> {
+    let chosenMaterial: Material | null = this.viewer.scene.materials.find(mat => mat.id === materialId) ?? null;
+
+    if (!chosenMaterial) {
+      // material not available yet, request it from Combeenation assets
+      const existingCreationProm = this._createMaterialPromises[materialId];
+      if (existingCreationProm !== undefined) {
+        // request is already pending, just wait for the result
+        chosenMaterial = await existingCreationProm;
+      } else {
+        this.viewer.eventManager.fireEvent(ViewerEvent.MaterialCreationStart, materialId);
+
+        // request not pending, call the dedicated function
+        const newCreationProm = this._createMaterial(materialId, mesh);
+        // store the promise in a global map, so that subsequent requests can reference it
+        this._createMaterialPromises[materialId] = newCreationProm;
+        chosenMaterial = await newCreationProm;
+
+        delete this._createMaterialPromises[materialId];
+
+        const allMaterialsCreated = !Object.entries(this._createMaterialPromises).length;
+        // signalize event system that material is created now
+        // also check if there are other material creation processes still pending, as this is an important information
+        // e.g. for showing load masks
+        this.viewer.eventManager.fireEvent(ViewerEvent.MaterialCreationEnd, materialId, allMaterialsCreated);
+      }
+    }
+
+    return chosenMaterial as Material;
+  }
+
+  protected async _createMaterial(materialId: string, mesh?: AbstractMesh): Promise<Material> {
+    if (materialId === MaterialManager.CBN_FALLBACK_MATERIAL_NAME) {
+      const fallbackMaterial = new StandardMaterial(MaterialManager.CBN_FALLBACK_MATERIAL_NAME, this.viewer.scene);
+      fallbackMaterial.disableLighting = true;
+
+      return fallbackMaterial;
+    }
+
+    const materialDefinition = await window.Cbn?.Assets.getMaterial(materialId);
+    // The generic `Material.Parse` actually returns a more specific material like `BABYLON.StandardMaterial`,
+    // `BABYLON.PBRMaterial` or stuff like `BABYLON.PBRMetallicRoughnessMaterial` etc. based on the given `customType`
+    // within the material JSON definition
+    const material = materialDefinition && Material.Parse(materialDefinition, this.viewer.scene, '');
+
+    if (!material) {
+      throw new ViewerError({
+        id: ViewerErrorIds.MaterialCouldNotBeParsed,
+        message: `Material with id "${materialId}" could not be parsed`,
+      });
+    }
+
+    await this.viewer.parameterManager.applyParameterValuesToMaterial(material);
+
+    const matReadyProms = [
+      new Promise<void>(resolve => BaseTexture.WhenAllReady(material.getActiveTextures(), resolve)),
+    ];
+
+    if (mesh) {
+      // 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
+      matReadyProms.push(material.forceCompilationAsync(mesh));
+    }
+
+    // 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(matReadyProms);
+
+    return material;
+  }
+}

package/src/manager/modelManager.ts

@@ -0,0 +1,456 @@
+import {
+  AssetContainer,
+  BuiltInParameter,
+  MaterialManager,
+  MeshBuilder,
+  ParameterManager,
+  SceneLoader,
+  TransformNode,
+  Viewer,
+  ViewerError,
+  ViewerErrorIds,
+} from '../index';
+import { cloneModelAssetContainer } from '../internal/cloningHelper';
+import { getInternalMetadataValue } from '../internal/metadataHelper';
+import { isArray } from 'lodash-es';
+
+export type ModelAssetDefinition = {
+  name: string;
+  url: string;
+};
+
+export type ModelVisibilityEntry = {
+  name: string;
+  visible: boolean;
+};
+
+/**
+ * Callback for renaming nodes when cloning nodes in a model
+ */
+export type NodeNamingStrategy = (node: TransformNode, newModelName: string) => string;
+/**
+ * Callback for renaming tags when cloning nodes in a model
+ */
+export type TagNamingStrategy = (tag: string, newModelName: string) => string;
+
+export type ModelCloneOptions = {
+  nodeNamingStrategy: NodeNamingStrategy;
+  tagNamingStrategy: TagNamingStrategy;
+};
+
+type Model = {
+  name: string;
+  url: string;
+  state: ModelAssetState;
+  assetContainer: AssetContainer;
+  isClone: boolean;
+  visibilityCallId?: number;
+};
+
+type ModelAssetState = 'notLoaded' | 'loading' | 'loaded' | 'inScene';
+
+/**
+ * Manager for handling 3d models.\
+ * Responsible for loading models and handling their visibility.\
+ * Also contains advanced features like model cloning.
+ */
+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 = {
+    name: ModelManager.CBN_FALLBACK_MODEL_ASSET_NAME,
+    url: '',
+    state: 'loaded',
+    assetContainer: new AssetContainer(),
+    isClone: false,
+  };
+  protected _loadModelPromises: { [modelName: string]: Promise<void> } = {};
+
+  get modelNames(): string[] {
+    return Object.keys(this._modelAssets);
+  }
+
+  /**
+   * Nested models were targeted with slash notation previously, as Spec couldn't work with dots.
+   * Dots were interpreted as inherited model.
+   * Now the Hive viewer parameters are returning slash notated asset names, whereas the asset names from the
+   * prepacked asset manager are dot notated.
+   * This function converts slash to dot notation, so that models can be target with slash and dot notation alike.
+   */
+  protected static _replaceSlashes(inputStr: string): string {
+    return inputStr.split('/').join('.');
+  }
+
+  public constructor(protected viewer: Viewer) {}
+
+  /**
+   * Creates content for the fallback model, which is actually just a black cube.
+   * This is used for 3d assets that are linked in a data source but not available (yet).
+   * The Combeenation backend exchanges the missing 3d asset name with "$fallback", which indicates that we shouldn't
+   * throw an error but just show the fallback model instead.
+   *
+   * @internal
+   */
+  public createFallbackModel(): void {
+    const fallbackCube = MeshBuilder.CreateBox('$fallbackCube', { size: 1 }, this.viewer.scene);
+    fallbackCube._parentContainer = this._fallbackModelAsset.assetContainer;
+    this._fallbackModelAsset.assetContainer.meshes.push(fallbackCube);
+    // NOTE: this is theoretically async, but in reality it's not when getting the material description from the CBN
+    // server
+    // also this is just a fallback that shouldn't be relevant in productive configurators
+    this.viewer.materialManager.setMaterialOnMesh(MaterialManager.CBN_FALLBACK_MATERIAL_NAME, fallbackCube);
+
+    this._fallbackModelAsset.assetContainer.removeFromScene();
+  }
+
+  /**
+   * Register models for 3d viewer, this is required for each model before it can be loaded/shown.\
+   * The "viewer control" inside the Combeenation framework calls this function automatically with all assigned
+   * 3d assets.
+   */
+  public registerModels(modelAssets: ModelAssetDefinition[]): void {
+    for (const { name, url } of modelAssets) {
+      const existingModel = this._modelAssets[name];
+      if (existingModel) {
+        console.warn(`Model ${name} is already registered`);
+        return;
+      }
+
+      const model: Model = { name, url, state: 'notLoaded', assetContainer: new AssetContainer(), isClone: false };
+      this._modelAssets[name] = model;
+    }
+  }
+
+  /**
+   * Loads the model and all it's assigned materials.\
+   * This function should be used for "eager loading" of models, so that model switching will be instant in the
+   * process.\
+   * If you don't plan to do this, just use {@link setModelVisibility} as this function will load the model under the
+   * hood the first time the model gets visible.
+   */
+  public async loadModel(name: string): Promise<void> {
+    const model = this._getModel(name);
+    if (!model) {
+      throw new ViewerError({
+        id: ViewerErrorIds.ModelNotRegistered,
+        message: `Can't load model "${name}" as model is not registered`,
+      });
+    }
+
+    if (model.state !== 'notLoaded') {
+      console.warn(`Model ${name} is already loaded or currently loading`);
+      return;
+    }
+
+    await this._loadModel(model);
+    await this._prepareModelForScene(model);
+  }
+
+  /**
+   * Enables/disables multiple one or multiple models simultaniously.\
+   * All required models are loaded before adjusting the visibility to avoid flashing in the 3d scene.
+   *
+   * @returns Array of changed visibility status, combined with the corresponding model name
+   */
+  public async setModelVisibility(
+    modelVisibility: ModelVisibilityEntry | ModelVisibilityEntry[]
+  ): Promise<ModelVisibilityEntry[]> {
+    const showModels: Model[] = [];
+    const hideModels: Model[] = [];
+
+    if (!isArray(modelVisibility)) {
+      modelVisibility = [modelVisibility];
+    }
+
+    for (const entry of modelVisibility) {
+      const model = this._getModel(entry.name);
+      if (!model) {
+        throw new ViewerError({
+          id: ViewerErrorIds.ModelNotRegistered,
+          message: `Can't set visibility of model "${entry.name}" as model is not registered`,
+        });
+      }
+
+      // 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;
+
+      if (entry.visible) {
+        if (model.state === 'notLoaded') {
+          await this._loadModel(model);
+
+          // check if this is still the latest visibility call
+          if (model.visibilityCallId === curVisibilityCallId) {
+            showModels.push(model);
+          }
+        } else if (model.state === 'loading') {
+          await this._loadModelPromises[model.name];
+
+          if (model.visibilityCallId === curVisibilityCallId) {
+            showModels.push(model);
+          }
+        } else if (model.state === 'loaded') {
+          showModels.push(model);
+        }
+      } else {
+        if (model.state === 'loading') {
+          await this._loadModelPromises[model.name];
+
+          if (model.visibilityCallId === curVisibilityCallId) {
+            hideModels.push(model);
+          }
+        } else if (model.state === 'inScene') {
+          hideModels.push(model);
+        }
+      }
+    }
+
+    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);
+    }
+
+    const returnVal: ModelVisibilityEntry[] = [];
+    showModels.forEach(showModel => returnVal.push({ name: showModel.name, visible: true }));
+    hideModels.forEach(hideModel => returnVal.push({ name: hideModel.name, visible: false }));
+
+    return returnVal;
+  }
+
+  /**
+   * Create a clone of an existing model.\
+   * Only the geometry (meshes, transform nodes) gets cloned, as materials are typically shared across the whole scene.
+   *
+   * @param show show model immediately after cloning
+   * @param options additional options for the cloning procedure, like renaming algorithms
+   */
+  public async cloneModel(
+    name: string,
+    newModelName: string,
+    show: boolean = true,
+    options?: ModelCloneOptions
+  ): Promise<void> {
+    const sourceModel = this._getModel(name);
+    if (!sourceModel) {
+      throw new ViewerError({
+        id: ViewerErrorIds.ModelNotRegistered,
+        message: `Can't clone model "${name}" as model is not registered`,
+      });
+    }
+
+    const existingModel = this._getModel(newModelName);
+    if (existingModel) {
+      throw new ViewerError({
+        id: ViewerErrorIds.ModelAlreadyExists,
+        message: `Can't create clone as model "${newModelName}" already exists`,
+      });
+    }
+
+    if (sourceModel.state === 'notLoaded') {
+      await this._loadModel(sourceModel);
+    } else if (sourceModel.state === 'loading') {
+      await this._loadModelPromises[sourceModel.name];
+    }
+
+    const clonedModel: Model = {
+      name: newModelName,
+      url: sourceModel.url,
+      state: 'loaded',
+      assetContainer: cloneModelAssetContainer(
+        sourceModel.assetContainer,
+        newModelName,
+        {
+          nodeNamingStrategy: options?.nodeNamingStrategy,
+          tagNamingStrategy: options?.tagNamingStrategy,
+        },
+        this.viewer.scene
+      ),
+      isClone: true,
+    };
+    this._modelAssets[newModelName] = clonedModel;
+
+    if (show) {
+      await this._showModel(clonedModel);
+    }
+  }
+
+  /**
+   * Removes a cloned model from the scene and from the internal model storage.\
+   * Deleted clones can not be shown again.
+   */
+  public deleteClonedModel(name: string): void {
+    const model = this._getModel(name);
+    if (!model) {
+      throw new ViewerError({
+        id: ViewerErrorIds.ModelNotRegistered,
+        message: `Can't delete cloned model "${name}" as model is not registered`,
+      });
+    }
+
+    if (!model.isClone) {
+      throw new ViewerError({
+        id: ViewerErrorIds.ModelIsNotAClone,
+        message: `Can't delete model "${name}" as model is not a clone`,
+      });
+    }
+
+    model.assetContainer.dispose();
+
+    delete this._modelAssets[name];
+  }
+
+  /**
+   * Removes all cloned models from the scene and the internal model storage.
+   */
+  public deleteAllClonedModels(): void {
+    const clonedModelNames = Object.values(this._modelAssets)
+      .filter(model => model.isClone)
+      .map(model => model.name);
+
+    clonedModelNames.forEach(modelName => this.deleteClonedModel(modelName));
+  }
+
+  /**
+   * Loads and returns the asset container of a certain model.\
+   * This can be used to access the models content without having to add it to the scene.\
+   * A typical use case is to clone or instantiate a node from a "library" model.
+   */
+  public async getAssetContainerOfModel(name: string): Promise<AssetContainer> {
+    const model = this._getModel(name);
+    if (!model) {
+      throw new ViewerError({
+        id: ViewerErrorIds.ModelNotRegistered,
+        message: `Can't get asset container of model "${name}" as model is not registered`,
+      });
+    }
+
+    if (model.state === 'notLoaded') {
+      await this._loadModel(model);
+    } else if (model.state === 'loading') {
+      await this._loadModelPromises[model.name];
+    }
+
+    await this._prepareModelForScene(model);
+
+    return model.assetContainer;
+  }
+
+  /**
+   * Get model by name
+   */
+  protected _getModel(name: string): Model | undefined {
+    if (name === '$fallback') {
+      return this._fallbackModelAsset;
+    }
+
+    const replacedName = ModelManager._replaceSlashes(name);
+    const model = this._modelAssets[replacedName];
+
+    return model;
+  }
+
+  /**
+   * Load model into scene, but don't show it immediately
+   */
+  protected async _loadModel(model: Model): Promise<void> {
+    const loadModelPromise = async (): Promise<void> => {
+      model.state = 'loading';
+      const curEnvTexture = this.viewer.scene.environmentTexture;
+      const curEnvIntensity = this.viewer.scene.environmentIntensity;
+
+      let assetContainer;
+      try {
+        assetContainer = await SceneLoader.LoadAssetContainerAsync('', model.url, this.viewer.scene);
+      } catch (e) {
+        throw new ViewerError({
+          id: ViewerErrorIds.AssetLoadingFailed,
+          message: `Error loading model "${model.name}" from url "${model.url}":\n${(e as Error).message}`,
+        });
+      }
+
+      // 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());
+
+      // 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';
+
+      delete this._loadModelPromises[model.name];
+    };
+
+    this._loadModelPromises[model.name] = loadModelPromise();
+    return this._loadModelPromises[model.name];
+  }
+
+  /**
+   * Apply parameter to the model in the asset container.
+   * 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> {
+    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);
+  }
+
+  /**
+   * Add assets of asset container to scene, do the scene preparation if required.
+   * CAUTION: model is expected to be in the correct loading state already.
+   *
+   * @param skipPreparation optionally skip applying parameter values to model before showing it
+   *                        (see {@link _prepareModelForScene})
+   */
+  protected async _showModel(model: Model, skipPreparation?: boolean): Promise<void> {
+    if (!skipPreparation) {
+      await this._prepareModelForScene(model);
+    }
+
+    model.assetContainer.addToScene();
+    model.state = 'inScene';
+  }
+
+  /**
+   * Remove assets of asset container from scene
+   */
+  protected _hideModel(model: Model): 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);
+      }
+    }
+  }
+}