@combeenation/3d-viewer 12.4.1 → 12.4.3

package/src/api/util/babylonHelper.ts

@@ -1,915 +1,915 @@
-import { DottedPath } from '../classes/dottedPath';
-import { Event, emitter } from '../classes/event';
-import { defaultEnvHelperColor, defaultSceneClearColor } from '../internal/sceneSetup';
-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';
-import { ShadowGenerator } from '@babylonjs/core/Lights/Shadows/shadowGenerator';
-import { Light } from '@babylonjs/core/Lights/light';
-import { PBRMaterial } from '@babylonjs/core/Materials/PBR/pbrMaterial';
-import { BaseTexture } from '@babylonjs/core/Materials/Textures/baseTexture';
-import { CubeTexture } from '@babylonjs/core/Materials/Textures/cubeTexture';
-import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
-import { Texture } from '@babylonjs/core/Materials/Textures/texture';
-import { Material } from '@babylonjs/core/Materials/material';
-import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
-import { Axis } from '@babylonjs/core/Maths/math.axis';
-import { Color3, Color4 } from '@babylonjs/core/Maths/math.color';
-import { Quaternion, Vector3 } from '@babylonjs/core/Maths/math.vector';
-import { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
-import { InstancedMesh } from '@babylonjs/core/Meshes/instancedMesh';
-import { Mesh } from '@babylonjs/core/Meshes/mesh';
-import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
-import { Observable } from '@babylonjs/core/Misc/observable';
-import { Tags } from '@babylonjs/core/Misc/tags';
-import { Tools } from '@babylonjs/core/Misc/tools';
-import { Node } from '@babylonjs/core/node';
-import { Scene } from '@babylonjs/core/scene';
-import { Nullable } from '@babylonjs/core/types';
-import { get, has, merge, uniq } from 'lodash-es';
-
-const backgroundDomeName = 'BackgroundDome_ViewerGenerated';
-const envHelperMetadataName = 'viewerEnvHelper';
-const materialWaitingToBeSetMetadataName = 'materialWaitingToBeSet';
-
-// Holds pending `createMaterialFromCbnAssets` promises for dedicated material ids
-// In this case we can make sure that a single material is not requested multiple times if used in various nodes
-const getMaterialPromises: Map<string, Promise<Material | null>> = new Map();
-
-/**
- * @param node
- * @return Node
- */
-const getRootNode = function (node: Node): Node {
-  let _node = node;
-  while (_node.parent) {
-    _node = _node.parent;
-  }
-  return _node;
-};
-
-/**
- * @param nodes
- * @param predicate
- * @return Map<DottedPath, T>
- */
-const mapToDottedNodes = function <T>(nodes: Node[], predicate?: (node: Node) => boolean): Map<DottedPath, T> {
-  const map = new Map<DottedPath, T>();
-  const addNodes = function (_node: Node) {
-    if (predicate && predicate(_node)) {
-      map.set(_node.metadata.dottedPath, _node as any);
-    }
-    _node.getChildren().forEach(child => {
-      addNodes(child);
-    });
-  };
-  nodes.forEach(node => {
-    addNodes(node);
-  });
-  return map;
-};
-
-/**
- * @param node
- * @return DottedPath
- */
-const getDottedPathForNode = function (node: Node): DottedPath {
-  const dottedPath = DottedPath.create(node.name);
-  let _parent = node;
-  while (_parent.parent) {
-    _parent = _parent.parent;
-    dottedPath.unshiftPart(_parent.name);
-  }
-  return dottedPath;
-};
-
-/**
- * @param node
- * @param nodeNamingStrategy
- * @param predicate
- * @param deep
- * @return TransformNode | null
- */
-const cloneTransformNode = function (
-  node: TransformNode,
-  nodeNamingStrategy: NodeNamingStrategy,
-  predicate?: (node: TransformNode) => boolean,
-  deep: boolean = true
-): TransformNode | null {
-  if (predicate && !predicate(node)) {
-    return null;
-  }
-  const newName = nodeNamingStrategy.handler(node, nodeNamingStrategy.payload);
-  const clone = node.clone(newName, node.parent, true);
-  if (clone) {
-    clone.id = newName;
-    injectMetadata(clone, { cloneSource: node }, false);
-    injectMetadata(node, { cloneTarget: clone }, false);
-    // if the cloned node is of type InstancedMesh, due to a bug(?),
-    // the InstancedMesh.isEnabled state may have changed after cloning.
-    // in that case, set the clone's enabled state to the original's state
-    if (node instanceof InstancedMesh) {
-      clone.setEnabled(node.isEnabled(false));
-
-      // tags are not cloned for instanced meshes by default
-      if (Tags.HasTags(node)) {
-        Tags.AddTagsTo(clone, Tags.GetTags(node, true));
-      }
-    }
-  }
-  if (deep) {
-    const children = node.getChildTransformNodes(true);
-    children.forEach(child => {
-      const clonedChild = cloneTransformNode(child, nodeNamingStrategy, predicate, deep);
-      if (clonedChild) {
-        clonedChild.parent = clone;
-      }
-    });
-  }
-  return clone;
-};
-
-/**
- * @param node
- */
-const cloneNodeWithParents = function (node: Node | null): Node | null {
-  let clone = null;
-  if (node instanceof TransformNode) {
-    clone = node.clone(node.name, cloneNodeWithParents(node.parent) as Nullable<Node>, true);
-  } else if (node instanceof Light) {
-    clone = node.clone(node.name, cloneNodeWithParents(node.parent) as Nullable<Node>);
-  } else if (node) {
-    throw new Error(`Cloning of "${node?.constructor.name}" is not implemented (yet).`);
-  }
-  return clone;
-};
-
-/**
- * @param node
- * @param deep
- * @param prefix
- * @return TransformNode
- */
-const cloneTransformNodeMaterial = function (
-  node: TransformNode,
-  prefix: DottedPathArgument = '',
-  deep: boolean = true
-): TransformNode {
-  if (node instanceof AbstractMesh && node.material) {
-    const newMatName = DottedPath.create(prefix).addParts([node.material.name, 'clone', node.uniqueId.toString()]);
-    node.material = node.material.clone(newMatName.path);
-  }
-  if (deep) {
-    const children = node.getChildTransformNodes(true);
-    children.forEach(child => cloneTransformNodeMaterial(child, prefix, deep));
-  }
-  return node;
-};
-
-/**
- * @param object
- * @param deep
- * @param metadata
- */
-const injectMetadata = function (object: Node | Material | BaseTexture, metadata: {}, deep: boolean = true) {
-  object.metadata = merge({}, object.metadata, metadata);
-  if (deep && object instanceof TransformNode) {
-    const children = object.getChildTransformNodes(true);
-    children.forEach(child => injectMetadata(child, metadata, deep));
-  }
-};
-
-/**
- * @param node
- * @param assertCallable
- * @param callableParameters
- * @param deep
- */
-const assertTransformNode = function (
-  node: TransformNode,
-  assertCallable: (node: TransformNode, ...args: any[]) => void,
-  callableParameters: any[] = [],
-  deep: boolean = true
-) {
-  assertCallable(node, ...callableParameters);
-  if (deep) {
-    const children = node.getChildTransformNodes(true);
-    children.forEach(child => assertTransformNode(child, assertCallable, callableParameters, deep));
-  }
-};
-
-/**
- * @param node
- * @param parameter
- */
-const assertMeshCapability = function (node: TransformNode, parameter: string) {
-  if (!(node instanceof AbstractMesh)) {
-    const cls = node.getClassName();
-    throw new Error(
-      `Changing parameter "${parameter}" of a(n) ${cls} is not supported. Tried to change node "${node.id}".`
-    );
-  }
-  if (node instanceof InstancedMesh) {
-    throw new Error(
-      `Changing parameter "${parameter}" of an InstancedMesh is not supported. Tried to change node "${node.id}".`
-    );
-  }
-};
-
-/**
- * @param node
- * @param deep
- */
-const activateTransformNode = function (node: TransformNode, deep: boolean = true) {
-  node.setEnabled(true);
-  /*
-	if( node instanceof AbstractMesh ) {
-		node.visibility = 1;
-		node.isPickable = true;
-	}
-	*/
-  if (deep) {
-    node.getChildTransformNodes(true).forEach(child => activateTransformNode(child, deep));
-  }
-};
-
-/**
- * @param node
- * @param deep
- */
-const deactivateTransformNode = function (node: TransformNode, deep: boolean = true) {
-  node.setEnabled(false);
-  /*
-	if( node instanceof AbstractMesh ) {
-		node.visibility = 0;
-		node.isPickable = false;
-	}
-	*/
-  if (deep) {
-    node.getChildTransformNodes(true).forEach(child => deactivateTransformNode(child, deep));
-  }
-};
-
-/**
- * @param node
- */
-const enableNodeWithParents = function (node: Node) {
-  node.setEnabled(true);
-  if (node.parent) {
-    enableNodeWithParents(node.parent);
-  }
-};
-
-/**
- * @param node
- */
-const disableNodeWithParents = function (node: Node) {
-  node.setEnabled(false);
-  if (node.parent) {
-    disableNodeWithParents(node.parent);
-  }
-};
-
-/**
- * Applies a {@link TransformationDefinition} consecutively to ensure dependencies in positioning etc.
- * @param node
- * @param transformation
- */
-const transformTransformNode = function (node: TransformNode, transformation: TransformationDefinition) {
-  // scaling
-  if (!has(node.metadata, 'scaling.initial')) {
-    injectMetadata(node, { 'scaling.initial': node.scaling }, false);
-  }
-  const initialScaling = get(node.metadata, 'scaling.initial') as Vector3;
-  node.scaling = initialScaling.multiply(transformation.scaling);
-  // position
-  if (!has(node.metadata, 'position.initial')) {
-    injectMetadata(node, { 'position.initial': node.absolutePosition.clone() }, false);
-  }
-  const initialPosition = get(node.metadata, 'position.initial') as Vector3;
-  node.setAbsolutePosition(initialPosition.add(transformation.position).multiply(transformation.scaling));
-  // rotation
-  if (!has(node.metadata, 'rotation.initial')) {
-    let rotationQuaternion = node.rotationQuaternion;
-    if (!rotationQuaternion) {
-      rotationQuaternion = Quaternion.RotationYawPitchRoll(node.rotation.x, node.rotation.y, node.rotation.z);
-    }
-    injectMetadata(node, { 'rotation.initial': rotationQuaternion.asArray() }, false);
-  }
-  const initialRotationQuaternion = Quaternion.FromArray(get(node.metadata, 'rotation.initial') as []);
-  node.rotationQuaternion = initialRotationQuaternion;
-  node.rotateAround(Vector3.Zero(), Axis.X, transformation.rotation.x);
-  node.rotateAround(Vector3.Zero(), Axis.Y, transformation.rotation.y);
-  node.rotateAround(Vector3.Zero(), Axis.Z, transformation.rotation.z);
-  node.computeWorldMatrix(true);
-};
-
-/**
- * Apply changes of environment (background texture, etc.) consecutively in order to avoid dependency related issues.
- * @param scene
- * @param envDef
- */
-const changeEnvironment = function (scene: Scene, envDef: EnvironmentDefinition) {
-  // issue warning if both background texture and usedefault are set
-  if (envDef.environmentUseDefault && envDef.environmentBackground) {
-    console.warn(
-      `!!! Warning !!! Spec parameter 'environment.usedefault' is being overruled by 'environment.background'.`
-    );
-  }
-
-  const useDefaultEnv = envDef.environmentUseDefault && !envDef.environmentBackground;
-
-  // 1) set ENVIRONMENT_COLOR
-  const clearColorBefore = scene.clearColor.toString();
-  scene.clearColor = envDef.environmentColor
-    ? Color4.FromColor3(envDef.environmentColor)
-    : useDefaultEnv
-    ? defaultEnvHelperColor
-    : defaultSceneClearColor;
-  const clearColorChanged = clearColorBefore !== scene.clearColor.toString();
-
-  // 2) dispose existing & set new ENVIRONMENT (==texture)
-  const curEnvTexture = scene.environmentTexture as Nullable<CubeTexture>;
-  const envTextureChanged = envDef.environment !== curEnvTexture?.url;
-
-  if (curEnvTexture && (!envDef.environment || envTextureChanged)) {
-    curEnvTexture.dispose();
-  }
-
-  const rotation = envDef.environmentRotation !== undefined ? Tools.ToRadians(envDef.environmentRotation) : 0;
-  if (envDef.environment && envTextureChanged) {
-    const envTexture = CubeTexture.CreateFromPrefilteredData(envDef.environment, scene);
-    envTexture.rotationY = rotation;
-    scene.environmentTexture = envTexture;
-  } else if (curEnvTexture && curEnvTexture.rotationY !== rotation) {
-    curEnvTexture.rotationY = rotation;
-  }
-
-  // 3) dispose existing & set new ENVIRONMENT_BACKGROUND
-  const curDome = scene.getNodeByName(backgroundDomeName) as undefined | PhotoDome;
-  const backgroundUrlChanged = envDef.environmentBackground !== curDome?.texture.url;
-
-  if (curDome && (!envDef.environmentBackground || backgroundUrlChanged)) {
-    curDome.dispose();
-  }
-
-  const rotationPhotoDome = -1 * rotation;
-  if (envDef.environmentBackground && backgroundUrlChanged) {
-    const textureUrl = envDef.environmentBackground;
-    const dome = new PhotoDome(backgroundDomeName, textureUrl, { resolution: 32, size: 450 }, scene);
-    // Rotate submesh to get them in line with environment texture
-    dome.getChildMeshes(true)[0].rotation.y = Tools.ToRadians(90);
-    dome.rotation.y = rotationPhotoDome;
-  } else if (curDome && curDome.rotation.y !== rotationPhotoDome) {
-    curDome.rotation.y = rotationPhotoDome;
-  }
-
-  // 4) dispose existing & set new ENVIRONMENT_USEDEFAULT (only if no background is set)
-  const curEnvHelper = scene.metadata?.[envHelperMetadataName] as undefined | EnvironmentHelper;
-
-  if (curEnvHelper && !useDefaultEnv) {
-    curEnvHelper.dispose();
-    delete scene.metadata[envHelperMetadataName];
-  }
-
-  const envHelperMainColor = Color3.FromArray(scene.clearColor.asArray());
-  if (useDefaultEnv && !curEnvHelper) {
-    const envHelper = scene.createDefaultEnvironment({ sizeAuto: true });
-    envHelper?.setMainColor(envHelperMainColor);
-    if (envHelper) {
-      scene.metadata = merge({}, scene.metadata, { [envHelperMetadataName]: envHelper });
-    }
-  } else if (curEnvHelper && useDefaultEnv && clearColorChanged) {
-    curEnvHelper.setMainColor(envHelperMainColor);
-  }
-
-  // 5) set ENVIRONMENT_INTENSITY
-  if (envDef.environmentIntensity !== undefined) {
-    scene.environmentIntensity = envDef.environmentIntensity;
-  }
-};
-
-/**
- * Sets a material by a given material id as material property on the given node.
- *
- * If the material is not already available in the scene, the viewer tries to create a material based on a Combeenation
- * [material asset](https://docs.combeenation.com/docs/howto-create-and-use-babylon-and-material-asset).
- * This of course only works if the viewer is used inside a Combeenation configurator.
- *
- * Furthermore this function also defers the material creation if the node is not visible yet to improve network &
- * viewer bootstrap performance as textures are automatically being lazy loaded only when they are actually visible in
- * the scene.
- *
- * Finally the material will not be applied before all its textures have been loaded. In this way "flickering" effects
- * will be avoided, since the material would be incomplete without its loaded textures.
- */
-const setMaterial = function (node: TransformNode, materialId: string, deep: boolean = true, variant?: Variant) {
-  if (node instanceof AbstractMesh) {
-    const materialExists = node.getScene().getMaterialById(materialId);
-    const hasMissingMaterial = has(node.metadata, missingMaterialMetadataName);
-    const deferMaterialCreation = !materialExists && !node.isEnabled();
-    if (deferMaterialCreation) {
-      // do not set the material
-      injectMetadata(node, { [missingMaterialMetadataName]: materialId }, false);
-      // if it already had the missing material flag before, there already exists an observer...
-      if (!hasMissingMaterial) {
-        addMissingMaterialObserver(node);
-      }
-    } else {
-      // create material and apply it when textures have been loaded
-      getOrCreateMaterial(node.getScene(), materialId, variant).then(material => {
-        applyMaterial(material, node).then(() => emitter.emit(Event.MESH_MATERIAL_APPLIED, node, material));
-
-        if (hasMissingMaterial) {
-          delete node.metadata[missingMaterialMetadataName];
-        }
-      });
-    }
-  }
-  // recursively set materials on children (if desired)
-  if (deep) {
-    for (const child of node.getChildTransformNodes(true)) {
-      setMaterial(child, materialId, deep, variant);
-    }
-  }
-};
-
-/**
- * Removes material from promise map once it has been added to the scene, because we can be sure that the material will
- * be taken from the scene directly, the next time it is requested
- */
-const onNewMaterialAddedCb = (material: Material) => {
-  if (getMaterialPromises.has(material.id)) {
-    getMaterialPromises.delete(material.id);
-  }
-};
-
-/**
- * Responsible for adding the `onNewMaterialAddedCb` only once
- */
-const registerOnNewMaterialAddedCbOnce = (scene: Scene) => {
-  const observerAlreadyAssigned = scene.onNewMaterialAddedObservable.observers.find(
-    observer => observer.callback === onNewMaterialAddedCb
-  );
-
-  if (!observerAlreadyAssigned) {
-    scene.onNewMaterialAddedObservable.add(onNewMaterialAddedCb);
-  }
-};
-
-/**
- * Gets the Material either from the given {@link Variant}, the given scene or tries to create it from an Combeenation
- * material asset when inside a Combeenation configurator.
- */
-const getOrCreateMaterial = async function (scene: Scene, materialId: string, variant?: Variant): Promise<Material> {
-  registerOnNewMaterialAddedCbOnce(scene);
-
-  let chosenMaterial: Material | undefined | null;
-  chosenMaterial = variant?.inheritedMaterials.find(mat => mat.id === materialId);
-  chosenMaterial = chosenMaterial || scene.materials.find(mat => mat.id === materialId);
-
-  if (!chosenMaterial) {
-    // material not available yet, request it from Combeenation assets
-    if (getMaterialPromises.has(materialId)) {
-      // request is already pending, just wait for the result
-      chosenMaterial = await getMaterialPromises.get(materialId);
-    } else {
-      // request not pending, call the dedicated function
-      const getMaterialProm = createMaterialFromCbnAssets(materialId, scene);
-      // store the promise in a global map, so that subsequent requests can reference it
-      getMaterialPromises.set(materialId, getMaterialProm);
-      chosenMaterial = await getMaterialProm;
-    }
-  }
-
-  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 shaders are compiled.
- * Then sets the material on the node if there is no newer "set material" request
- */
-const applyMaterial = async function (material: Material, node: AbstractMesh) {
-  // set current material id as last valid id, in this case all previously set materials on the node will be invalidated
-  injectMetadata(node, { [materialWaitingToBeSetMetadataName]: material.id }, false);
-
-  const promTexturesReady = new Promise<void>(resolve =>
-    BaseTexture.WhenAllReady(material.getActiveTextures(), resolve)
-  );
-  // this promise should only take some time on the first call of the corresponding shader (eg: PBRMaterial shader)
-  // on each other call of the same material/shader type there should be not be a waiting time, or at maximum one frame
-  // https://forum.babylonjs.com/t/mesh-flickering-when-setting-material-initially/37312
-  const promMaterialCompiled = material.forceCompilationAsync(node);
-
-  // material needs to fulfill 2 criterias before it's ready to use
-  // - textures need to be "ready" => downloaded
-  // - dedicated shader needs to be compiled
-  // if this would not be the case you can see some "flickering" when setting the material
-  await Promise.all([promTexturesReady, promMaterialCompiled]);
-
-  // textures ready, now check if the material is still up-to-date
-  if (material.id === node.metadata?.[materialWaitingToBeSetMetadataName]) {
-    node.material = material;
-    delete node.metadata[materialWaitingToBeSetMetadataName];
-  }
-};
-
-/**
- * !!! Warning !!!
- * This function is not public API. Whilst it can help solving certain problems, it only works reliably in well defined
- * situations and can cause unwanted side effects under some conditions. Use carefully at your own risk!
- *
- * See https://combeenation.myjetbrains.com/youtrack/issue/CB-5906 for further details regarding this warning.
- *
- * Set material of an instanced meshes source mesh.
- * Changes the material of all instanced meshes which have the same source mesh.
- *
- * @param node
- * @param material
- * @param deep
- *
- * @ignore
- */
-const setSourceNodeMaterial = function (node: TransformNode, material: Material, deep: boolean = true) {
-  const warn = `	You're using "setSourceNodeMaterial" which is not public API.
-	Whilst it can help solving certain problems, it only works reliably in well defined situations and can cause unwanted side effects under some conditions.
-	Use carefully at your own risk!`;
-  console.warn(`!!! Warning !!!\n${warn}`);
-
-  if (node instanceof InstancedMesh) {
-    node.sourceMesh.material = material;
-  }
-  if (deep) {
-    node.getChildTransformNodes(true).forEach(child => setSourceNodeMaterial(child, material, deep));
-  }
-};
-
-/**
- * @param node
- * @param color
- * @param deep
- */
-const setMaterialColor = function (node: TransformNode, color: Color3, deep: boolean = true) {
-  if (node instanceof AbstractMesh && node.material) {
-    const materialCls = node.material.getClassName();
-    switch (materialCls) {
-      case 'PBRMaterial':
-        (node.material as PBRMaterial).albedoColor = color.toLinearSpace();
-        break;
-      case 'StandardMaterial':
-        (node.material as StandardMaterial).diffuseColor = color;
-        break;
-      default:
-        throw new Error(`Setting color for material of instance "${materialCls}" not implemented (yet).`);
-    }
-    setMaterial(node, node.material.id, false);
-  }
-  if (deep) {
-    node.getChildTransformNodes(true).forEach(child => setMaterialColor(child, color, deep));
-  }
-};
-
-/**
- * @param node
- * @param texture
- * @param deep
- */
-const setMaterialTexture = function (node: TransformNode, texture: Texture, deep: boolean = true) {
-  if (node instanceof AbstractMesh && node.material) {
-    const materialCls = node.material.getClassName();
-    switch (materialCls) {
-      case 'PBRMaterial':
-        (node.material as PBRMaterial).albedoTexture = texture;
-        break;
-      case 'StandardMaterial':
-        (node.material as StandardMaterial).diffuseTexture = texture;
-        break;
-      default:
-        throw new Error(`Setting texture for material of instance "${materialCls}" not implemented (yet).`);
-    }
-    setMaterial(node, node.material.id, false);
-  }
-  if (deep) {
-    node.getChildTransformNodes(true).forEach(child => setMaterialTexture(child, texture, deep));
-  }
-};
-
-/**
- * @param node
- * @param metallness
- * @param deep
- */
-const setMaterialMetallness = function (node: TransformNode, metallness: number, deep: boolean = true) {
-  if (node instanceof AbstractMesh && node.material) {
-    const materialCls = node.material.getClassName();
-    switch (materialCls) {
-      case 'PBRMaterial':
-        (node.material as PBRMaterial).metallic = metallness;
-        break;
-      default:
-        throw new Error(`Setting metallness for material of instance "${materialCls}" not implemented (yet).`);
-    }
-    setMaterial(node, node.material.id, false);
-  }
-  if (deep) {
-    node.getChildTransformNodes(true).forEach(child => setMaterialMetallness(child, metallness, deep));
-  }
-};
-
-/**
- * @param node
- * @param roughness
- * @param deep
- */
-const setMaterialRoughness = function (node: TransformNode, roughness: number, deep: boolean = true) {
-  if (node instanceof AbstractMesh && node.material) {
-    const materialCls = node.material.getClassName();
-    switch (materialCls) {
-      case 'PBRMaterial':
-        (node.material as PBRMaterial).roughness = roughness;
-        break;
-      case 'StandardMaterial':
-        (node.material as StandardMaterial).roughness = roughness;
-        break;
-      default:
-        throw new Error(`Setting roughness for material of instance "${materialCls}" not implemented (yet).`);
-    }
-    setMaterial(node, node.material.id, false);
-  }
-  if (deep) {
-    node.getChildTransformNodes(true).forEach(child => setMaterialRoughness(child, roughness, deep));
-  }
-};
-
-/**
- * @param node
- * @param layer
- * @param color
- * @param deep
- */
-const addToHighlightLayer = function (layer: HighlightLayer, color: Color3, node: TransformNode, deep: boolean = true) {
-  if (node instanceof AbstractMesh) {
-    layer.addMesh(node as Mesh, color);
-  }
-  if (deep) {
-    node.getChildTransformNodes(true).forEach(child => addToHighlightLayer(layer, color, child, deep));
-  }
-};
-
-/**
- * @param node
- * @param layer
- * @param deep
- */
-const removeFromHighlightLayer = function (layer: HighlightLayer, node: TransformNode, deep: boolean = true) {
-  if (node instanceof AbstractMesh) {
-    layer.removeMesh(node as Mesh);
-  }
-  if (deep) {
-    node.getChildTransformNodes(true).forEach(child => removeFromHighlightLayer(layer, child, deep));
-  }
-};
-
-/**
- * @param node
- * @param receiveShadows
- * @param deep
- */
-const setReceiveShadows = function (node: TransformNode, receiveShadows: boolean, deep: boolean = true) {
-  if (node instanceof AbstractMesh) {
-    node.receiveShadows = receiveShadows;
-  }
-  if (deep) {
-    node.getChildTransformNodes(true).forEach(child => setReceiveShadows(child, receiveShadows, deep));
-  }
-};
-
-/**
- * @param node
- * @param generator
- * @param deep
- */
-const addToShadowGenerator = function (generator: ShadowGenerator, node: TransformNode, deep: boolean = true) {
-  if (node instanceof AbstractMesh) {
-    // We have to remove the node because there's no duplicate check in babylon
-    generator.removeShadowCaster(node, false);
-    generator.addShadowCaster(node, false);
-  }
-  if (deep) {
-    node.getChildTransformNodes(true).forEach(child => addToShadowGenerator(generator, child, deep));
-  }
-};
-
-/**
- * @param node
- * @param generator
- * @param deep
- */
-const removeFromShadowGenerator = function (generator: ShadowGenerator, node: TransformNode, deep: boolean = true) {
-  if (node instanceof AbstractMesh) {
-    generator.removeShadowCaster(node, false);
-  }
-  if (deep) {
-    node.getChildTransformNodes(true).forEach(child => removeFromShadowGenerator(generator, child, deep));
-  }
-};
-
-/**
- * https://forum.babylonjs.com/t/get-mesh-bounding-box-position-and-size-in-2d-screen-coordinates/1058/3
- * @param mesh
- * @param scene
- * @param canvas
- */
-const getClientRectFromMesh = function (mesh: AbstractMesh, scene: Scene, canvas: HTMLCanvasElement): ClientRect {
-  // get bounding box of the mesh
-  const meshVectors = mesh.getBoundingInfo().boundingBox.vectors;
-  // get the matrix and viewport needed to project the vectors onto the screen
-  const worldMatrix = mesh.getWorldMatrix();
-  const transformMatrix = scene.getTransformMatrix();
-  const viewport = scene.activeCamera!.viewport;
-  // loop though all the vectors and project them against the current camera viewport to get a set of coordinates
-  const coordinates = meshVectors.map(vector => {
-    const projection = Vector3.Project(vector, worldMatrix, transformMatrix, viewport);
-    projection.x = projection.x * canvas.clientWidth;
-    projection.y = projection.y * canvas.clientHeight;
-    return projection;
-  });
-  // get the min and max for all the coordinates so we can calculate the largest possible screen size
-  const maxX = Math.max(...coordinates.map(o => o.x));
-  const minX = Math.min(...coordinates.map(o => o.x));
-  const maxY = Math.max(...coordinates.map(o => o.y));
-  const minY = Math.min(...coordinates.map(o => o.y));
-  // return a ClientRect from this
-  return {
-    width: maxX - minX,
-    height: maxY - minY,
-    left: minX,
-    top: minY,
-    right: maxX,
-    bottom: maxY,
-  } as ClientRect;
-};
-
-type LoadableBaseTexture = BaseTexture & {
-  url: string;
-  onLoadObservable: Observable<BaseTexture>;
-};
-
-/**
- * This type guard checks whether the given `BaseTextures` is any of its subtypes which comes with an url and
- * `onLoadObservable`.
- *
- * !!! Timing of when this function is called is important !!!
- * See the following for more details: https://forum.babylonjs.com/t/basetexture-whenallready-returns-too-early/34501/6
- */
-const isLoadableTexture = function (texture: BaseTexture): texture is LoadableBaseTexture {
-  const castedTexture = texture as LoadableBaseTexture;
-  return !!castedTexture.url && !!castedTexture.onLoadObservable;
-};
-
-/**
- * @param objects
- * @param tagMapping
- */
-const mapTags = function (objects: object[], tagMapping: TagMapping): string[] {
-  let affectedTags: string[] = [];
-  for (const object of objects) {
-    const oldTags = Object.keys(Tags.GetTags(object, false) ?? {});
-    const mappedTags = oldTags.map(t => tagMapping[t] || t);
-    Tags.RemoveTagsFrom(object, oldTags.join(' '));
-    Tags.AddTagsTo(object, mappedTags.join(' '));
-    affectedTags = [...affectedTags, ...mappedTags];
-  }
-  return uniq(affectedTags);
-};
-
-/**
- * Gets an array of ids for nodeIds that exist in both TransformNode arrays.
- * @param nodes1
- * @param nodes2
- * @param predicate
- */
-const intersectingNodeNames = function (nodes1: Node[], nodes2: Node[], predicate?: (node: Node) => boolean): string[] {
-  const nodeNames1 = nodes1.filter(n => !predicate || predicate(n)).map(n => n.name);
-  const nodesNames2 = nodes2.filter(n => !predicate || predicate(n)).map(n => n.name);
-  return nodeNames1.filter(n1 => nodesNames2.includes(n1));
-};
-
-/**
- * Gets an array of ids for duplicate nodeIds in given node array.
- * @param nodes
- * @param predicate
- */
-const duplicateNodeNames = function (nodes: Node[], predicate?: (node: Node) => boolean): string[] {
-  const nodeNames = nodes.filter(n => !predicate || predicate(n)).map(n => n.name);
-  return nodeNames.filter((v, i, self) => self.indexOf(v) !== i);
-};
-
-/**
- * Reports duplicate nodeIds.
- * @param nodeNames
- */
-const reportDuplicateNodeNames = function (nodeNames: string[]): void {
-  if (nodeNames.length > 0) {
-    const warn = `There are duplicate nodeNames: ${nodeNames.join(', ')}`;
-    console.warn(`!!! Warning !!!\n${warn}`);
-    window.Cbn?.Assets.reportDuplicateNodeName(nodeNames);
-  }
-};
-
-const drawPaintableOnMaterial = function (
-  material: Material,
-  imageSource: HTMLImageElement,
-  scene: Scene,
-  options?: PaintableOptions
-) {
-  // always take width and height from image source, scaling is done with uvScale properties
-  const widthAndHeight = {
-    width: imageSource.width,
-    height: imageSource.height,
-  };
-
-  const texture = new DynamicTexture(`${material.id}.paintable_texture`, widthAndHeight, scene);
-
-  // draw image on texture
-  const ctx = texture.getContext();
-  ctx.drawImage(imageSource, 0, 0);
-  texture.update();
-
-  // apply settings from paintable options to tweak position and scaling of image on the texture
-  texture.uScale = options?.uScale ?? texture.uScale;
-  texture.vScale = options?.vScale ?? texture.vScale;
-  texture.uOffset = options?.uOffset ?? texture.uOffset;
-  texture.vOffset = options?.vOffset ?? texture.vOffset;
-
-  // wrap mode is preferred, as it will always show the texture, no matter which position offset is currently chosen
-  // clamp mode requires more knowledge (and patience) when adjusting the uv scale and offset values
-  texture.wrapU = Texture.WRAP_ADDRESSMODE;
-  texture.wrapV = Texture.WRAP_ADDRESSMODE;
-
-  // apply the paintable texture on the dedicated material type
-  const materialCls = material.getClassName();
-  switch (materialCls) {
-    case 'PBRMaterial':
-      (material as PBRMaterial).albedoTexture = texture;
-      break;
-    case 'StandardMaterial':
-      (material as StandardMaterial).diffuseTexture = texture;
-      break;
-    default:
-      throw new Error(`Setting paintable texture for material of instance "${materialCls}" not implemented (yet).`);
-  }
-};
-
-export {
-  getRootNode,
-  isLoadableTexture,
-  mapToDottedNodes,
-  getDottedPathForNode,
-  cloneTransformNode,
-  cloneNodeWithParents,
-  cloneTransformNodeMaterial,
-  getOrCreateMaterial,
-  applyMaterial,
-  injectMetadata,
-  assertTransformNode,
-  assertMeshCapability,
-  activateTransformNode,
-  deactivateTransformNode,
-  enableNodeWithParents,
-  disableNodeWithParents,
-  transformTransformNode,
-  setMaterial,
-  setSourceNodeMaterial,
-  setMaterialColor,
-  setMaterialTexture,
-  setMaterialMetallness,
-  setMaterialRoughness,
-  addToHighlightLayer,
-  removeFromHighlightLayer,
-  setReceiveShadows,
-  addToShadowGenerator,
-  removeFromShadowGenerator,
-  getClientRectFromMesh,
-  changeEnvironment,
-  backgroundDomeName,
-  envHelperMetadataName,
-  mapTags,
-  intersectingNodeNames,
-  duplicateNodeNames,
-  reportDuplicateNodeNames,
-  drawPaintableOnMaterial,
-};
+import { DottedPath } from '../classes/dottedPath';
+import { Event, emitter } from '../classes/event';
+import { defaultEnvHelperColor, defaultSceneClearColor } from '../internal/sceneSetup';
+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';
+import { ShadowGenerator } from '@babylonjs/core/Lights/Shadows/shadowGenerator';
+import { Light } from '@babylonjs/core/Lights/light';
+import { PBRMaterial } from '@babylonjs/core/Materials/PBR/pbrMaterial';
+import { BaseTexture } from '@babylonjs/core/Materials/Textures/baseTexture';
+import { CubeTexture } from '@babylonjs/core/Materials/Textures/cubeTexture';
+import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
+import { Texture } from '@babylonjs/core/Materials/Textures/texture';
+import { Material } from '@babylonjs/core/Materials/material';
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
+import { Axis } from '@babylonjs/core/Maths/math.axis';
+import { Color3, Color4 } from '@babylonjs/core/Maths/math.color';
+import { Quaternion, Vector3 } from '@babylonjs/core/Maths/math.vector';
+import { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
+import { InstancedMesh } from '@babylonjs/core/Meshes/instancedMesh';
+import { Mesh } from '@babylonjs/core/Meshes/mesh';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { Observable } from '@babylonjs/core/Misc/observable';
+import { Tags } from '@babylonjs/core/Misc/tags';
+import { Tools } from '@babylonjs/core/Misc/tools';
+import { Node } from '@babylonjs/core/node';
+import { Scene } from '@babylonjs/core/scene';
+import { Nullable } from '@babylonjs/core/types';
+import { get, has, merge, uniq } from 'lodash-es';
+
+const backgroundDomeName = 'BackgroundDome_ViewerGenerated';
+const envHelperMetadataName = 'viewerEnvHelper';
+const materialWaitingToBeSetMetadataName = 'materialWaitingToBeSet';
+
+// Holds pending `createMaterialFromCbnAssets` promises for dedicated material ids
+// In this case we can make sure that a single material is not requested multiple times if used in various nodes
+const getMaterialPromises: Map<string, Promise<Material | null>> = new Map();
+
+/**
+ * @param node
+ * @return Node
+ */
+const getRootNode = function (node: Node): Node {
+  let _node = node;
+  while (_node.parent) {
+    _node = _node.parent;
+  }
+  return _node;
+};
+
+/**
+ * @param nodes
+ * @param predicate
+ * @return Map<DottedPath, T>
+ */
+const mapToDottedNodes = function <T>(nodes: Node[], predicate?: (node: Node) => boolean): Map<DottedPath, T> {
+  const map = new Map<DottedPath, T>();
+  const addNodes = function (_node: Node) {
+    if (predicate && predicate(_node)) {
+      map.set(_node.metadata.dottedPath, _node as any);
+    }
+    _node.getChildren().forEach(child => {
+      addNodes(child);
+    });
+  };
+  nodes.forEach(node => {
+    addNodes(node);
+  });
+  return map;
+};
+
+/**
+ * @param node
+ * @return DottedPath
+ */
+const getDottedPathForNode = function (node: Node): DottedPath {
+  const dottedPath = DottedPath.create(node.name);
+  let _parent = node;
+  while (_parent.parent) {
+    _parent = _parent.parent;
+    dottedPath.unshiftPart(_parent.name);
+  }
+  return dottedPath;
+};
+
+/**
+ * @param node
+ * @param nodeNamingStrategy
+ * @param predicate
+ * @param deep
+ * @return TransformNode | null
+ */
+const cloneTransformNode = function (
+  node: TransformNode,
+  nodeNamingStrategy: NodeNamingStrategy,
+  predicate?: (node: TransformNode) => boolean,
+  deep: boolean = true
+): TransformNode | null {
+  if (predicate && !predicate(node)) {
+    return null;
+  }
+  const newName = nodeNamingStrategy.handler(node, nodeNamingStrategy.payload);
+  const clone = node.clone(newName, node.parent, true);
+  if (clone) {
+    clone.id = newName;
+    injectMetadata(clone, { cloneSource: node }, false);
+    injectMetadata(node, { cloneTarget: clone }, false);
+    // if the cloned node is of type InstancedMesh, due to a bug(?),
+    // the InstancedMesh.isEnabled state may have changed after cloning.
+    // in that case, set the clone's enabled state to the original's state
+    if (node instanceof InstancedMesh) {
+      clone.setEnabled(node.isEnabled(false));
+
+      // tags are not cloned for instanced meshes by default
+      if (Tags.HasTags(node)) {
+        Tags.AddTagsTo(clone, Tags.GetTags(node, true));
+      }
+    }
+  }
+  if (deep) {
+    const children = node.getChildTransformNodes(true);
+    children.forEach(child => {
+      const clonedChild = cloneTransformNode(child, nodeNamingStrategy, predicate, deep);
+      if (clonedChild) {
+        clonedChild.parent = clone;
+      }
+    });
+  }
+  return clone;
+};
+
+/**
+ * @param node
+ */
+const cloneNodeWithParents = function (node: Node | null): Node | null {
+  let clone = null;
+  if (node instanceof TransformNode) {
+    clone = node.clone(node.name, cloneNodeWithParents(node.parent) as Nullable<Node>, true);
+  } else if (node instanceof Light) {
+    clone = node.clone(node.name, cloneNodeWithParents(node.parent) as Nullable<Node>);
+  } else if (node) {
+    throw new Error(`Cloning of "${node?.constructor.name}" is not implemented (yet).`);
+  }
+  return clone;
+};
+
+/**
+ * @param node
+ * @param deep
+ * @param prefix
+ * @return TransformNode
+ */
+const cloneTransformNodeMaterial = function (
+  node: TransformNode,
+  prefix: DottedPathArgument = '',
+  deep: boolean = true
+): TransformNode {
+  if (node instanceof AbstractMesh && node.material) {
+    const newMatName = DottedPath.create(prefix).addParts([node.material.name, 'clone', node.uniqueId.toString()]);
+    node.material = node.material.clone(newMatName.path);
+  }
+  if (deep) {
+    const children = node.getChildTransformNodes(true);
+    children.forEach(child => cloneTransformNodeMaterial(child, prefix, deep));
+  }
+  return node;
+};
+
+/**
+ * @param object
+ * @param deep
+ * @param metadata
+ */
+const injectMetadata = function (object: Node | Material | BaseTexture, metadata: {}, deep: boolean = true) {
+  object.metadata = merge({}, object.metadata, metadata);
+  if (deep && object instanceof TransformNode) {
+    const children = object.getChildTransformNodes(true);
+    children.forEach(child => injectMetadata(child, metadata, deep));
+  }
+};
+
+/**
+ * @param node
+ * @param assertCallable
+ * @param callableParameters
+ * @param deep
+ */
+const assertTransformNode = function (
+  node: TransformNode,
+  assertCallable: (node: TransformNode, ...args: any[]) => void,
+  callableParameters: any[] = [],
+  deep: boolean = true
+) {
+  assertCallable(node, ...callableParameters);
+  if (deep) {
+    const children = node.getChildTransformNodes(true);
+    children.forEach(child => assertTransformNode(child, assertCallable, callableParameters, deep));
+  }
+};
+
+/**
+ * @param node
+ * @param parameter
+ */
+const assertMeshCapability = function (node: TransformNode, parameter: string) {
+  if (!(node instanceof AbstractMesh)) {
+    const cls = node.getClassName();
+    throw new Error(
+      `Changing parameter "${parameter}" of a(n) ${cls} is not supported. Tried to change node "${node.id}".`
+    );
+  }
+  if (node instanceof InstancedMesh) {
+    throw new Error(
+      `Changing parameter "${parameter}" of an InstancedMesh is not supported. Tried to change node "${node.id}".`
+    );
+  }
+};
+
+/**
+ * @param node
+ * @param deep
+ */
+const activateTransformNode = function (node: TransformNode, deep: boolean = true) {
+  node.setEnabled(true);
+  /*
+	if( node instanceof AbstractMesh ) {
+		node.visibility = 1;
+		node.isPickable = true;
+	}
+	*/
+  if (deep) {
+    node.getChildTransformNodes(true).forEach(child => activateTransformNode(child, deep));
+  }
+};
+
+/**
+ * @param node
+ * @param deep
+ */
+const deactivateTransformNode = function (node: TransformNode, deep: boolean = true) {
+  node.setEnabled(false);
+  /*
+	if( node instanceof AbstractMesh ) {
+		node.visibility = 0;
+		node.isPickable = false;
+	}
+	*/
+  if (deep) {
+    node.getChildTransformNodes(true).forEach(child => deactivateTransformNode(child, deep));
+  }
+};
+
+/**
+ * @param node
+ */
+const enableNodeWithParents = function (node: Node) {
+  node.setEnabled(true);
+  if (node.parent) {
+    enableNodeWithParents(node.parent);
+  }
+};
+
+/**
+ * @param node
+ */
+const disableNodeWithParents = function (node: Node) {
+  node.setEnabled(false);
+  if (node.parent) {
+    disableNodeWithParents(node.parent);
+  }
+};
+
+/**
+ * Applies a {@link TransformationDefinition} consecutively to ensure dependencies in positioning etc.
+ * @param node
+ * @param transformation
+ */
+const transformTransformNode = function (node: TransformNode, transformation: TransformationDefinition) {
+  // scaling
+  if (!has(node.metadata, 'scaling.initial')) {
+    injectMetadata(node, { 'scaling.initial': node.scaling }, false);
+  }
+  const initialScaling = get(node.metadata, 'scaling.initial') as Vector3;
+  node.scaling = initialScaling.multiply(transformation.scaling);
+  // position
+  if (!has(node.metadata, 'position.initial')) {
+    injectMetadata(node, { 'position.initial': node.absolutePosition.clone() }, false);
+  }
+  const initialPosition = get(node.metadata, 'position.initial') as Vector3;
+  node.setAbsolutePosition(initialPosition.add(transformation.position).multiply(transformation.scaling));
+  // rotation
+  if (!has(node.metadata, 'rotation.initial')) {
+    let rotationQuaternion = node.rotationQuaternion;
+    if (!rotationQuaternion) {
+      rotationQuaternion = Quaternion.RotationYawPitchRoll(node.rotation.x, node.rotation.y, node.rotation.z);
+    }
+    injectMetadata(node, { 'rotation.initial': rotationQuaternion.asArray() }, false);
+  }
+  const initialRotationQuaternion = Quaternion.FromArray(get(node.metadata, 'rotation.initial') as []);
+  node.rotationQuaternion = initialRotationQuaternion;
+  node.rotateAround(Vector3.Zero(), Axis.X, transformation.rotation.x);
+  node.rotateAround(Vector3.Zero(), Axis.Y, transformation.rotation.y);
+  node.rotateAround(Vector3.Zero(), Axis.Z, transformation.rotation.z);
+  node.computeWorldMatrix(true);
+};
+
+/**
+ * Apply changes of environment (background texture, etc.) consecutively in order to avoid dependency related issues.
+ * @param scene
+ * @param envDef
+ */
+const changeEnvironment = function (scene: Scene, envDef: EnvironmentDefinition) {
+  // issue warning if both background texture and usedefault are set
+  if (envDef.environmentUseDefault && envDef.environmentBackground) {
+    console.warn(
+      `!!! Warning !!! Spec parameter 'environment.usedefault' is being overruled by 'environment.background'.`
+    );
+  }
+
+  const useDefaultEnv = envDef.environmentUseDefault && !envDef.environmentBackground;
+
+  // 1) set ENVIRONMENT_COLOR
+  const clearColorBefore = scene.clearColor.toString();
+  scene.clearColor = envDef.environmentColor
+    ? Color4.FromColor3(envDef.environmentColor)
+    : useDefaultEnv
+    ? defaultEnvHelperColor
+    : defaultSceneClearColor;
+  const clearColorChanged = clearColorBefore !== scene.clearColor.toString();
+
+  // 2) dispose existing & set new ENVIRONMENT (==texture)
+  const curEnvTexture = scene.environmentTexture as Nullable<CubeTexture>;
+  const envTextureChanged = envDef.environment !== curEnvTexture?.url;
+
+  if (curEnvTexture && (!envDef.environment || envTextureChanged)) {
+    curEnvTexture.dispose();
+  }
+
+  const rotation = envDef.environmentRotation !== undefined ? Tools.ToRadians(envDef.environmentRotation) : 0;
+  if (envDef.environment && envTextureChanged) {
+    const envTexture = CubeTexture.CreateFromPrefilteredData(envDef.environment, scene);
+    envTexture.rotationY = rotation;
+    scene.environmentTexture = envTexture;
+  } else if (curEnvTexture && curEnvTexture.rotationY !== rotation) {
+    curEnvTexture.rotationY = rotation;
+  }
+
+  // 3) dispose existing & set new ENVIRONMENT_BACKGROUND
+  const curDome = scene.getNodeByName(backgroundDomeName) as undefined | PhotoDome;
+  const backgroundUrlChanged = envDef.environmentBackground !== curDome?.texture.url;
+
+  if (curDome && (!envDef.environmentBackground || backgroundUrlChanged)) {
+    curDome.dispose();
+  }
+
+  const rotationPhotoDome = -1 * rotation;
+  if (envDef.environmentBackground && backgroundUrlChanged) {
+    const textureUrl = envDef.environmentBackground;
+    const dome = new PhotoDome(backgroundDomeName, textureUrl, { resolution: 32, size: 450 }, scene);
+    // Rotate submesh to get them in line with environment texture
+    dome.getChildMeshes(true)[0].rotation.y = Tools.ToRadians(90);
+    dome.rotation.y = rotationPhotoDome;
+  } else if (curDome && curDome.rotation.y !== rotationPhotoDome) {
+    curDome.rotation.y = rotationPhotoDome;
+  }
+
+  // 4) dispose existing & set new ENVIRONMENT_USEDEFAULT (only if no background is set)
+  const curEnvHelper = scene.metadata?.[envHelperMetadataName] as undefined | EnvironmentHelper;
+
+  if (curEnvHelper && !useDefaultEnv) {
+    curEnvHelper.dispose();
+    delete scene.metadata[envHelperMetadataName];
+  }
+
+  const envHelperMainColor = Color3.FromArray(scene.clearColor.asArray());
+  if (useDefaultEnv && !curEnvHelper) {
+    const envHelper = scene.createDefaultEnvironment({ sizeAuto: true });
+    envHelper?.setMainColor(envHelperMainColor);
+    if (envHelper) {
+      scene.metadata = merge({}, scene.metadata, { [envHelperMetadataName]: envHelper });
+    }
+  } else if (curEnvHelper && useDefaultEnv && clearColorChanged) {
+    curEnvHelper.setMainColor(envHelperMainColor);
+  }
+
+  // 5) set ENVIRONMENT_INTENSITY
+  if (envDef.environmentIntensity !== undefined) {
+    scene.environmentIntensity = envDef.environmentIntensity;
+  }
+};
+
+/**
+ * Sets a material by a given material id as material property on the given node.
+ *
+ * If the material is not already available in the scene, the viewer tries to create a material based on a Combeenation
+ * [material asset](https://docs.combeenation.com/docs/howto-create-and-use-babylon-and-material-asset).
+ * This of course only works if the viewer is used inside a Combeenation configurator.
+ *
+ * Furthermore this function also defers the material creation if the node is not visible yet to improve network &
+ * viewer bootstrap performance as textures are automatically being lazy loaded only when they are actually visible in
+ * the scene.
+ *
+ * Finally the material will not be applied before all its textures have been loaded. In this way "flickering" effects
+ * will be avoided, since the material would be incomplete without its loaded textures.
+ */
+const setMaterial = function (node: TransformNode, materialId: string, deep: boolean = true, variant?: Variant) {
+  if (node instanceof AbstractMesh) {
+    const materialExists = node.getScene().getMaterialById(materialId);
+    const hasMissingMaterial = has(node.metadata, missingMaterialMetadataName);
+    const deferMaterialCreation = !materialExists && !node.isEnabled();
+    if (deferMaterialCreation) {
+      // do not set the material
+      injectMetadata(node, { [missingMaterialMetadataName]: materialId }, false);
+      // if it already had the missing material flag before, there already exists an observer...
+      if (!hasMissingMaterial) {
+        addMissingMaterialObserver(node);
+      }
+    } else {
+      // create material and apply it when textures have been loaded
+      getOrCreateMaterial(node.getScene(), materialId, variant).then(material => {
+        applyMaterial(material, node).then(() => emitter.emit(Event.MESH_MATERIAL_APPLIED, node, material));
+
+        if (hasMissingMaterial) {
+          delete node.metadata[missingMaterialMetadataName];
+        }
+      });
+    }
+  }
+  // recursively set materials on children (if desired)
+  if (deep) {
+    for (const child of node.getChildTransformNodes(true)) {
+      setMaterial(child, materialId, deep, variant);
+    }
+  }
+};
+
+/**
+ * Removes material from promise map once it has been added to the scene, because we can be sure that the material will
+ * be taken from the scene directly, the next time it is requested
+ */
+const onNewMaterialAddedCb = (material: Material) => {
+  if (getMaterialPromises.has(material.id)) {
+    getMaterialPromises.delete(material.id);
+  }
+};
+
+/**
+ * Responsible for adding the `onNewMaterialAddedCb` only once
+ */
+const registerOnNewMaterialAddedCbOnce = (scene: Scene) => {
+  const observerAlreadyAssigned = scene.onNewMaterialAddedObservable.observers.find(
+    observer => observer.callback === onNewMaterialAddedCb
+  );
+
+  if (!observerAlreadyAssigned) {
+    scene.onNewMaterialAddedObservable.add(onNewMaterialAddedCb);
+  }
+};
+
+/**
+ * Gets the Material either from the given {@link Variant}, the given scene or tries to create it from an Combeenation
+ * material asset when inside a Combeenation configurator.
+ */
+const getOrCreateMaterial = async function (scene: Scene, materialId: string, variant?: Variant): Promise<Material> {
+  registerOnNewMaterialAddedCbOnce(scene);
+
+  let chosenMaterial: Material | undefined | null;
+  chosenMaterial = variant?.inheritedMaterials.find(mat => mat.id === materialId);
+  chosenMaterial = chosenMaterial || scene.materials.find(mat => mat.id === materialId);
+
+  if (!chosenMaterial) {
+    // material not available yet, request it from Combeenation assets
+    if (getMaterialPromises.has(materialId)) {
+      // request is already pending, just wait for the result
+      chosenMaterial = await getMaterialPromises.get(materialId);
+    } else {
+      // request not pending, call the dedicated function
+      const getMaterialProm = createMaterialFromCbnAssets(materialId, scene);
+      // store the promise in a global map, so that subsequent requests can reference it
+      getMaterialPromises.set(materialId, getMaterialProm);
+      chosenMaterial = await getMaterialProm;
+    }
+  }
+
+  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 shaders are compiled.
+ * Then sets the material on the node if there is no newer "set material" request
+ */
+const applyMaterial = async function (material: Material, node: AbstractMesh) {
+  // set current material id as last valid id, in this case all previously set materials on the node will be invalidated
+  injectMetadata(node, { [materialWaitingToBeSetMetadataName]: material.id }, false);
+
+  const promTexturesReady = new Promise<void>(resolve =>
+    BaseTexture.WhenAllReady(material.getActiveTextures(), resolve)
+  );
+  // this promise should only take some time on the first call of the corresponding shader (eg: PBRMaterial shader)
+  // on each other call of the same material/shader type there should be not be a waiting time, or at maximum one frame
+  // https://forum.babylonjs.com/t/mesh-flickering-when-setting-material-initially/37312
+  const promMaterialCompiled = material.forceCompilationAsync(node);
+
+  // material needs to fulfill 2 criterias before it's ready to use
+  // - textures need to be "ready" => downloaded
+  // - dedicated shader needs to be compiled
+  // if this would not be the case you can see some "flickering" when setting the material
+  await Promise.all([promTexturesReady, promMaterialCompiled]);
+
+  // textures ready, now check if the material is still up-to-date
+  if (material.id === node.metadata?.[materialWaitingToBeSetMetadataName]) {
+    node.material = material;
+    delete node.metadata[materialWaitingToBeSetMetadataName];
+  }
+};
+
+/**
+ * !!! Warning !!!
+ * This function is not public API. Whilst it can help solving certain problems, it only works reliably in well defined
+ * situations and can cause unwanted side effects under some conditions. Use carefully at your own risk!
+ *
+ * See https://combeenation.myjetbrains.com/youtrack/issue/CB-5906 for further details regarding this warning.
+ *
+ * Set material of an instanced meshes source mesh.
+ * Changes the material of all instanced meshes which have the same source mesh.
+ *
+ * @param node
+ * @param material
+ * @param deep
+ *
+ * @ignore
+ */
+const setSourceNodeMaterial = function (node: TransformNode, material: Material, deep: boolean = true) {
+  const warn = `	You're using "setSourceNodeMaterial" which is not public API.
+	Whilst it can help solving certain problems, it only works reliably in well defined situations and can cause unwanted side effects under some conditions.
+	Use carefully at your own risk!`;
+  console.warn(`!!! Warning !!!\n${warn}`);
+
+  if (node instanceof InstancedMesh) {
+    node.sourceMesh.material = material;
+  }
+  if (deep) {
+    node.getChildTransformNodes(true).forEach(child => setSourceNodeMaterial(child, material, deep));
+  }
+};
+
+/**
+ * @param node
+ * @param color
+ * @param deep
+ */
+const setMaterialColor = function (node: TransformNode, color: Color3, deep: boolean = true) {
+  if (node instanceof AbstractMesh && node.material) {
+    const materialCls = node.material.getClassName();
+    switch (materialCls) {
+      case 'PBRMaterial':
+        (node.material as PBRMaterial).albedoColor = color.toLinearSpace();
+        break;
+      case 'StandardMaterial':
+        (node.material as StandardMaterial).diffuseColor = color;
+        break;
+      default:
+        throw new Error(`Setting color for material of instance "${materialCls}" not implemented (yet).`);
+    }
+    setMaterial(node, node.material.id, false);
+  }
+  if (deep) {
+    node.getChildTransformNodes(true).forEach(child => setMaterialColor(child, color, deep));
+  }
+};
+
+/**
+ * @param node
+ * @param texture
+ * @param deep
+ */
+const setMaterialTexture = function (node: TransformNode, texture: Texture, deep: boolean = true) {
+  if (node instanceof AbstractMesh && node.material) {
+    const materialCls = node.material.getClassName();
+    switch (materialCls) {
+      case 'PBRMaterial':
+        (node.material as PBRMaterial).albedoTexture = texture;
+        break;
+      case 'StandardMaterial':
+        (node.material as StandardMaterial).diffuseTexture = texture;
+        break;
+      default:
+        throw new Error(`Setting texture for material of instance "${materialCls}" not implemented (yet).`);
+    }
+    setMaterial(node, node.material.id, false);
+  }
+  if (deep) {
+    node.getChildTransformNodes(true).forEach(child => setMaterialTexture(child, texture, deep));
+  }
+};
+
+/**
+ * @param node
+ * @param metallness
+ * @param deep
+ */
+const setMaterialMetallness = function (node: TransformNode, metallness: number, deep: boolean = true) {
+  if (node instanceof AbstractMesh && node.material) {
+    const materialCls = node.material.getClassName();
+    switch (materialCls) {
+      case 'PBRMaterial':
+        (node.material as PBRMaterial).metallic = metallness;
+        break;
+      default:
+        throw new Error(`Setting metallness for material of instance "${materialCls}" not implemented (yet).`);
+    }
+    setMaterial(node, node.material.id, false);
+  }
+  if (deep) {
+    node.getChildTransformNodes(true).forEach(child => setMaterialMetallness(child, metallness, deep));
+  }
+};
+
+/**
+ * @param node
+ * @param roughness
+ * @param deep
+ */
+const setMaterialRoughness = function (node: TransformNode, roughness: number, deep: boolean = true) {
+  if (node instanceof AbstractMesh && node.material) {
+    const materialCls = node.material.getClassName();
+    switch (materialCls) {
+      case 'PBRMaterial':
+        (node.material as PBRMaterial).roughness = roughness;
+        break;
+      case 'StandardMaterial':
+        (node.material as StandardMaterial).roughness = roughness;
+        break;
+      default:
+        throw new Error(`Setting roughness for material of instance "${materialCls}" not implemented (yet).`);
+    }
+    setMaterial(node, node.material.id, false);
+  }
+  if (deep) {
+    node.getChildTransformNodes(true).forEach(child => setMaterialRoughness(child, roughness, deep));
+  }
+};
+
+/**
+ * @param node
+ * @param layer
+ * @param color
+ * @param deep
+ */
+const addToHighlightLayer = function (layer: HighlightLayer, color: Color3, node: TransformNode, deep: boolean = true) {
+  if (node instanceof AbstractMesh) {
+    layer.addMesh(node as Mesh, color);
+  }
+  if (deep) {
+    node.getChildTransformNodes(true).forEach(child => addToHighlightLayer(layer, color, child, deep));
+  }
+};
+
+/**
+ * @param node
+ * @param layer
+ * @param deep
+ */
+const removeFromHighlightLayer = function (layer: HighlightLayer, node: TransformNode, deep: boolean = true) {
+  if (node instanceof AbstractMesh) {
+    layer.removeMesh(node as Mesh);
+  }
+  if (deep) {
+    node.getChildTransformNodes(true).forEach(child => removeFromHighlightLayer(layer, child, deep));
+  }
+};
+
+/**
+ * @param node
+ * @param receiveShadows
+ * @param deep
+ */
+const setReceiveShadows = function (node: TransformNode, receiveShadows: boolean, deep: boolean = true) {
+  if (node instanceof AbstractMesh) {
+    node.receiveShadows = receiveShadows;
+  }
+  if (deep) {
+    node.getChildTransformNodes(true).forEach(child => setReceiveShadows(child, receiveShadows, deep));
+  }
+};
+
+/**
+ * @param node
+ * @param generator
+ * @param deep
+ */
+const addToShadowGenerator = function (generator: ShadowGenerator, node: TransformNode, deep: boolean = true) {
+  if (node instanceof AbstractMesh) {
+    // We have to remove the node because there's no duplicate check in babylon
+    generator.removeShadowCaster(node, false);
+    generator.addShadowCaster(node, false);
+  }
+  if (deep) {
+    node.getChildTransformNodes(true).forEach(child => addToShadowGenerator(generator, child, deep));
+  }
+};
+
+/**
+ * @param node
+ * @param generator
+ * @param deep
+ */
+const removeFromShadowGenerator = function (generator: ShadowGenerator, node: TransformNode, deep: boolean = true) {
+  if (node instanceof AbstractMesh) {
+    generator.removeShadowCaster(node, false);
+  }
+  if (deep) {
+    node.getChildTransformNodes(true).forEach(child => removeFromShadowGenerator(generator, child, deep));
+  }
+};
+
+/**
+ * https://forum.babylonjs.com/t/get-mesh-bounding-box-position-and-size-in-2d-screen-coordinates/1058/3
+ * @param mesh
+ * @param scene
+ * @param canvas
+ */
+const getClientRectFromMesh = function (mesh: AbstractMesh, scene: Scene, canvas: HTMLCanvasElement): ClientRect {
+  // get bounding box of the mesh
+  const meshVectors = mesh.getBoundingInfo().boundingBox.vectors;
+  // get the matrix and viewport needed to project the vectors onto the screen
+  const worldMatrix = mesh.getWorldMatrix();
+  const transformMatrix = scene.getTransformMatrix();
+  const viewport = scene.activeCamera!.viewport;
+  // loop though all the vectors and project them against the current camera viewport to get a set of coordinates
+  const coordinates = meshVectors.map(vector => {
+    const projection = Vector3.Project(vector, worldMatrix, transformMatrix, viewport);
+    projection.x = projection.x * canvas.clientWidth;
+    projection.y = projection.y * canvas.clientHeight;
+    return projection;
+  });
+  // get the min and max for all the coordinates so we can calculate the largest possible screen size
+  const maxX = Math.max(...coordinates.map(o => o.x));
+  const minX = Math.min(...coordinates.map(o => o.x));
+  const maxY = Math.max(...coordinates.map(o => o.y));
+  const minY = Math.min(...coordinates.map(o => o.y));
+  // return a ClientRect from this
+  return {
+    width: maxX - minX,
+    height: maxY - minY,
+    left: minX,
+    top: minY,
+    right: maxX,
+    bottom: maxY,
+  } as ClientRect;
+};
+
+type LoadableBaseTexture = BaseTexture & {
+  url: string;
+  onLoadObservable: Observable<BaseTexture>;
+};
+
+/**
+ * This type guard checks whether the given `BaseTextures` is any of its subtypes which comes with an url and
+ * `onLoadObservable`.
+ *
+ * !!! Timing of when this function is called is important !!!
+ * See the following for more details: https://forum.babylonjs.com/t/basetexture-whenallready-returns-too-early/34501/6
+ */
+const isLoadableTexture = function (texture: BaseTexture): texture is LoadableBaseTexture {
+  const castedTexture = texture as LoadableBaseTexture;
+  return !!castedTexture.url && !!castedTexture.onLoadObservable;
+};
+
+/**
+ * @param objects
+ * @param tagMapping
+ */
+const mapTags = function (objects: object[], tagMapping: TagMapping): string[] {
+  let affectedTags: string[] = [];
+  for (const object of objects) {
+    const oldTags = Object.keys(Tags.GetTags(object, false) ?? {});
+    const mappedTags = oldTags.map(t => tagMapping[t] || t);
+    Tags.RemoveTagsFrom(object, oldTags.join(' '));
+    Tags.AddTagsTo(object, mappedTags.join(' '));
+    affectedTags = [...affectedTags, ...mappedTags];
+  }
+  return uniq(affectedTags);
+};
+
+/**
+ * Gets an array of ids for nodeIds that exist in both TransformNode arrays.
+ * @param nodes1
+ * @param nodes2
+ * @param predicate
+ */
+const intersectingNodeNames = function (nodes1: Node[], nodes2: Node[], predicate?: (node: Node) => boolean): string[] {
+  const nodeNames1 = nodes1.filter(n => !predicate || predicate(n)).map(n => n.name);
+  const nodesNames2 = nodes2.filter(n => !predicate || predicate(n)).map(n => n.name);
+  return nodeNames1.filter(n1 => nodesNames2.includes(n1));
+};
+
+/**
+ * Gets an array of ids for duplicate nodeIds in given node array.
+ * @param nodes
+ * @param predicate
+ */
+const duplicateNodeNames = function (nodes: Node[], predicate?: (node: Node) => boolean): string[] {
+  const nodeNames = nodes.filter(n => !predicate || predicate(n)).map(n => n.name);
+  return nodeNames.filter((v, i, self) => self.indexOf(v) !== i);
+};
+
+/**
+ * Reports duplicate nodeIds.
+ * @param nodeNames
+ */
+const reportDuplicateNodeNames = function (nodeNames: string[]): void {
+  if (nodeNames.length > 0) {
+    const warn = `There are duplicate nodeNames: ${nodeNames.join(', ')}`;
+    console.warn(`!!! Warning !!!\n${warn}`);
+    window.Cbn?.Assets.reportDuplicateNodeName(nodeNames);
+  }
+};
+
+const drawPaintableOnMaterial = function (
+  material: Material,
+  imageSource: HTMLImageElement,
+  scene: Scene,
+  options?: PaintableOptions
+) {
+  // always take width and height from image source, scaling is done with uvScale properties
+  const widthAndHeight = {
+    width: imageSource.width,
+    height: imageSource.height,
+  };
+
+  const texture = new DynamicTexture(`${material.id}.paintable_texture`, widthAndHeight, scene);
+
+  // draw image on texture
+  const ctx = texture.getContext();
+  ctx.drawImage(imageSource, 0, 0);
+  texture.update();
+
+  // apply settings from paintable options to tweak position and scaling of image on the texture
+  texture.uScale = options?.uScale ?? texture.uScale;
+  texture.vScale = options?.vScale ?? texture.vScale;
+  texture.uOffset = options?.uOffset ?? texture.uOffset;
+  texture.vOffset = options?.vOffset ?? texture.vOffset;
+
+  // wrap mode is preferred, as it will always show the texture, no matter which position offset is currently chosen
+  // clamp mode requires more knowledge (and patience) when adjusting the uv scale and offset values
+  texture.wrapU = Texture.WRAP_ADDRESSMODE;
+  texture.wrapV = Texture.WRAP_ADDRESSMODE;
+
+  // apply the paintable texture on the dedicated material type
+  const materialCls = material.getClassName();
+  switch (materialCls) {
+    case 'PBRMaterial':
+      (material as PBRMaterial).albedoTexture = texture;
+      break;
+    case 'StandardMaterial':
+      (material as StandardMaterial).diffuseTexture = texture;
+      break;
+    default:
+      throw new Error(`Setting paintable texture for material of instance "${materialCls}" not implemented (yet).`);
+  }
+};
+
+export {
+  getRootNode,
+  isLoadableTexture,
+  mapToDottedNodes,
+  getDottedPathForNode,
+  cloneTransformNode,
+  cloneNodeWithParents,
+  cloneTransformNodeMaterial,
+  getOrCreateMaterial,
+  applyMaterial,
+  injectMetadata,
+  assertTransformNode,
+  assertMeshCapability,
+  activateTransformNode,
+  deactivateTransformNode,
+  enableNodeWithParents,
+  disableNodeWithParents,
+  transformTransformNode,
+  setMaterial,
+  setSourceNodeMaterial,
+  setMaterialColor,
+  setMaterialTexture,
+  setMaterialMetallness,
+  setMaterialRoughness,
+  addToHighlightLayer,
+  removeFromHighlightLayer,
+  setReceiveShadows,
+  addToShadowGenerator,
+  removeFromShadowGenerator,
+  getClientRectFromMesh,
+  changeEnvironment,
+  backgroundDomeName,
+  envHelperMetadataName,
+  mapTags,
+  intersectingNodeNames,
+  duplicateNodeNames,
+  reportDuplicateNodeNames,
+  drawPaintableOnMaterial,
+};