@combeenation/3d-viewer 6.0.0 → 6.1.0-beta2

package/src/api/util/babylonHelper.ts

@@ -1,645 +1,658 @@
-import { DottedPath } from '../classes/dottedPath';
-import { defaultEnvHelperColor, defaultSceneClearColor } from '../internal/sceneSetup';
-import { addMissingMaterialObserver, 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 { 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 { 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 } from 'lodash-es';
-
-const backgroundDomeName = 'BackgroundDome_ViewerGenerated';
-const envHelperMetadataName = 'viewerEnvHelper';
-
-/**
- * @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 predicate
- * @param deep
- * @return TransformNode | null
- */
-const cloneTransformNode = function (
-  node: TransformNode,
-  predicate?: (node: TransformNode) => boolean,
-  deep: boolean = true
-): TransformNode | null {
-  if (predicate && !predicate(node)) {
-    return null;
-  }
-  const clone = node.clone(node.name, node.parent, true);
-  if (clone) {
-    clone.metadata = cloneDeep(node.metadata);
-    // 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));
-    }
-  }
-  if (deep) {
-    const children = node.getChildTransformNodes(true);
-    children.forEach(child => {
-      const clonedChild = cloneTransformNode(child, 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: CallableFunction,
-  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 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;
-  }
-};
-
-/**
- * @param node
- * @param materialName
- * @param deep
- */
-const setMaterial = function (variant: Variant, node: TransformNode, materialName: string, deep: boolean = true) {
-  if (node instanceof AbstractMesh) {
-    const materialExists = variant.viewer.scene.getMaterialById(materialName);
-    const hasMissingMaterial = has(node.metadata, missingMaterialMetadataName);
-    const deferMaterialCreation = !materialExists && !node.isEnabled();
-
-    if (deferMaterialCreation) {
-      injectNodeMetadata(node, { [missingMaterialMetadataName]: materialName }, false);
-
-      // If it already had the missing material flag before, there already exists an observer...
-      if (!hasMissingMaterial) {
-        addMissingMaterialObserver(node);
-      }
-    } else {
-      node.material = variant.getOrCreateMaterial(materialName);
-      if (hasMissingMaterial) {
-        delete node.metadata[missingMaterialMetadataName];
-      }
-    }
-  }
-  if (deep) {
-    node.getChildTransformNodes(true).forEach(child => setMaterial(variant, child, materialName, deep));
-  }
-};
-
-/**
- * !!! 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).`);
-    }
-  }
-  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).`);
-    }
-  }
-  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).`);
-    }
-  }
-  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).`);
-    }
-  }
-  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;
-};
-
-export {
-  getRootNode,
-  mapToDottedNodes,
-  getDottedPathForNode,
-  cloneTransformNode,
-  cloneNodeWithParents,
-  cloneTransformNodeMaterial,
-  injectNodeMetadata,
-  assertTransformNode,
-  activateTransformNode,
-  deactivateTransformNode,
-  enableNodeWithParents,
-  disableNodeWithParents,
-  transformTransformNode,
-  setMaterial,
-  setSourceNodeMaterial,
-  setMaterialColor,
-  setMaterialTexture,
-  setMaterialMetallness,
-  setMaterialRoughness,
-  addToHighlightLayer,
-  removeFromHighlightLayer,
-  setReceiveShadows,
-  addToShadowGenerator,
-  removeFromShadowGenerator,
-  getClientRectFromMesh,
-  changeEnvironment,
-  backgroundDomeName,
-  envHelperMetadataName,
-};
+import { DottedPath } from '../classes/dottedPath';
+import { defaultEnvHelperColor, defaultSceneClearColor } from '../internal/sceneSetup';
+import { addMissingMaterialObserver, 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 { 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 } from 'lodash-es';
+
+const backgroundDomeName = 'BackgroundDome_ViewerGenerated';
+const envHelperMetadataName = 'viewerEnvHelper';
+
+/**
+ * @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 predicate
+ * @param deep
+ * @return TransformNode | null
+ */
+const cloneTransformNode = function (
+  node: TransformNode,
+  predicate?: (node: TransformNode) => boolean,
+  deep: boolean = true
+): TransformNode | null {
+  if (predicate && !predicate(node)) {
+    return null;
+  }
+  const clone = node.clone(node.name, node.parent, true);
+  if (clone) {
+    clone.metadata = cloneDeep(node.metadata);
+    // 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));
+    }
+  }
+  if (deep) {
+    const children = node.getChildTransformNodes(true);
+    children.forEach(child => {
+      const clonedChild = cloneTransformNode(child, 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: CallableFunction,
+  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 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;
+  }
+};
+
+/**
+ * @param node
+ * @param materialName
+ * @param deep
+ */
+const setMaterial = function (variant: Variant, node: TransformNode, materialName: string, deep: boolean = true) {
+  if (node instanceof AbstractMesh) {
+    const materialExists = variant.viewer.scene.getMaterialById(materialName);
+    const hasMissingMaterial = has(node.metadata, missingMaterialMetadataName);
+    const deferMaterialCreation = !materialExists && !node.isEnabled();
+
+    if (deferMaterialCreation) {
+      injectNodeMetadata(node, { [missingMaterialMetadataName]: materialName }, false);
+
+      // If it already had the missing material flag before, there already exists an observer...
+      if (!hasMissingMaterial) {
+        addMissingMaterialObserver(node);
+      }
+    } else {
+      node.material = variant.getOrCreateMaterial(materialName);
+      if (hasMissingMaterial) {
+        delete node.metadata[missingMaterialMetadataName];
+      }
+    }
+  }
+  if (deep) {
+    node.getChildTransformNodes(true).forEach(child => setMaterial(variant, child, materialName, deep));
+  }
+};
+
+/**
+ * !!! 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).`);
+    }
+  }
+  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).`);
+    }
+  }
+  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).`);
+    }
+  }
+  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).`);
+    }
+  }
+  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;
+};
+
+/**
+ * This type guard does not only check whether the given `BaseTexture` is of subtype `Texture`, but also whether it has
+ * been fully initialized or not.
+ *
+ * See the following for more details on why "is fully initialized" makes a difference in this regard:
+ * https://forum.babylonjs.com/t/basetexture-whenallready-returns-too-early/34501/4
+ */
+const isFullyInitializedTexture = function (texture: BaseTexture): texture is Texture {
+  return !!(texture as Texture).onLoadObservable;
+};
+
+export {
+  getRootNode,
+  isFullyInitializedTexture,
+  mapToDottedNodes,
+  getDottedPathForNode,
+  cloneTransformNode,
+  cloneNodeWithParents,
+  cloneTransformNodeMaterial,
+  injectNodeMetadata,
+  assertTransformNode,
+  activateTransformNode,
+  deactivateTransformNode,
+  enableNodeWithParents,
+  disableNodeWithParents,
+  transformTransformNode,
+  setMaterial,
+  setSourceNodeMaterial,
+  setMaterialColor,
+  setMaterialTexture,
+  setMaterialMetallness,
+  setMaterialRoughness,
+  addToHighlightLayer,
+  removeFromHighlightLayer,
+  setReceiveShadows,
+  addToShadowGenerator,
+  removeFromShadowGenerator,
+  getClientRectFromMesh,
+  changeEnvironment,
+  backgroundDomeName,
+  envHelperMetadataName,
+};