@combeenation/3d-viewer 0.0.1-types

package/src/api/util/babylonHelper.ts

@@ -0,0 +1,822 @@
+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 { 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 { cloneDeep, get, has, merge, uniq } from 'lodash-es';
+
+const backgroundDomeName = 'BackgroundDome_ViewerGenerated';
+const envHelperMetadataName = 'viewerEnvHelper';
+const materialWaitingToBeSetMetadataName = 'materialWaitingToBeSet';
+
+/**
+ * @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;
+    clone.metadata = cloneDeep(node.metadata);
+    injectNodeMetadata(clone, { cloneSource: node }, 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.constructor.name === 'InstancedMesh') {
+      clone.setEnabled(node.isEnabled(false));
+    }
+    // copying tags is a temporary workaround, as it doesn't work for TransformNodes ATM
+    // see https://forum.babylonjs.com/t/transformnode-clone-doesnt-contain-original-tags/38429/1
+    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 node
+ * @param deep
+ * @param metadata
+ */
+const injectNodeMetadata = function (node: Node, metadata: {}, deep: boolean = true) {
+  node.metadata = merge({}, node.metadata, metadata);
+  if (deep && node instanceof TransformNode) {
+    const children = node.getChildTransformNodes(true);
+    children.forEach(child => injectNodeMetadata(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')) {
+    injectNodeMetadata(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')) {
+    injectNodeMetadata(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);
+    }
+    injectNodeMetadata(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
+      injectNodeMetadata(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
+      const material = getOrCreateMaterial(node.getScene(), materialId, variant);
+      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);
+    }
+  }
+};
+
+/**
+ * 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 = function (scene: Scene, materialId: string, variant?: Variant): Material {
+  let chosenMaterial: Material | undefined | null;
+  chosenMaterial = variant?.inheritedMaterials.find(mat => mat.id === materialId);
+  chosenMaterial = chosenMaterial || scene.materials.find(mat => mat.id === materialId);
+  chosenMaterial = chosenMaterial || createMaterialFromCbnAssets(materialId, scene);
+  if (chosenMaterial) {
+    return chosenMaterial as Material;
+  }
+  // reject when material was not found
+  let rejectMessage = `Material with id "${materialId}" does not exist on scene.`;
+  if (variant) {
+    rejectMessage = `Material with id "${materialId}" does not exist for variant "${variant.id}".`;
+  }
+  throw new Error(rejectMessage);
+};
+
+/**
+ * Waits until the materials textures are loaded and 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
+  injectNodeMetadata(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 BaseTextureWithOnLoadObservable = BaseTexture & {
+  onLoadObservable: Observable<BaseTexture>;
+};
+
+/**
+ * This type guard checks whether the given `BaseTextures` is any of its subtypes which comes with an
+ * `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 isTextureWithOnLoadObservable = function (texture: BaseTexture): texture is BaseTextureWithOnLoadObservable {
+  return !!(texture as BaseTextureWithOnLoadObservable).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);
+  }
+};
+
+export {
+  getRootNode,
+  isTextureWithOnLoadObservable,
+  mapToDottedNodes,
+  getDottedPathForNode,
+  cloneTransformNode,
+  cloneNodeWithParents,
+  cloneTransformNodeMaterial,
+  getOrCreateMaterial,
+  applyMaterial,
+  injectNodeMetadata,
+  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,
+};