@combeenation/3d-viewer 14.0.0 → 14.0.1-rc1

package/src/manager/model-manager.ts

@@ -1,458 +1,458 @@
-import {
-  AssetContainer,
-  BuiltInParameter,
-  MaterialManager,
-  MeshBuilder,
-  ParameterManager,
-  SceneLoader,
-  TransformNode,
-  Viewer,
-  ViewerError,
-  ViewerErrorIds,
-} from '../index';
-import { cloneModelAssetContainer } from '../internal/cloning-helper';
-import { getInternalMetadataValue } from '../internal/metadata-helper';
-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];
-    }
-
-    if (model.state !== 'inScene') {
-      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);
-      }
-    }
-  }
-}
+import {
+  AssetContainer,
+  BuiltInParameter,
+  MaterialManager,
+  MeshBuilder,
+  ParameterManager,
+  SceneLoader,
+  TransformNode,
+  Viewer,
+  ViewerError,
+  ViewerErrorIds,
+} from '../index';
+import { cloneModelAssetContainer } from '../internal/cloning-helper';
+import { getInternalMetadataValue } from '../internal/metadata-helper';
+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];
+    }
+
+    if (model.state !== 'inScene') {
+      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);
+      }
+    }
+  }
+}