@combeenation/3d-viewer 4.0.0-alpha9 → 4.0.0-beta4

package/src/api/util/babylonHelper.ts

@@ -1,553 +1,392 @@
-import { HighlightLayer } from '@babylonjs/core/Layers/highlightLayer';
-import { Light } from '@babylonjs/core/Lights/light';
-import { ShadowGenerator } from '@babylonjs/core/Lights/Shadows/shadowGenerator';
-import { Material } from '@babylonjs/core/Materials/material';
-import { PBRMaterial } from '@babylonjs/core/Materials/PBR/pbrMaterial';
-import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
-import { Axis } from '@babylonjs/core/Maths/math.axis';
-import { Color3 } 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 { Node } from '@babylonjs/core/node';
-import { Scene } from '@babylonjs/core/scene';
-import { cloneDeep, get, has, merge } from 'lodash-es';
-import { DottedPath } from '../classes/dottedPath';
-
-/**
- * @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( 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 ), true );
-	} else if( node instanceof Light ) {
-		clone = node.clone( node.name, cloneNodeWithParents( node.parent ) );
-	} 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 _prefix = DottedPath.create( prefix ).addParts([
-			'node',
-			node.uniqueId.toString()
-		]);
-		node.material = node.material.clone( _prefix.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 );
-	}
-};
-
-/**
- * Attention: this function mutates the position of a node. Keep in mind that there are dependencies to other
- * functions moving nodes around.
- * @param node
- * @param rotation
- */
-const rotateTransformNode = function( node: TransformNode, rotation: Vector3 ): TransformNode {
-	// remember absolute rotation and reset it before translating
-	if( !has( node.metadata, 'rotation.initial' ) ) {
-		injectNodeMetadata( node, { 'rotation.initial': node.rotationQuaternion?.asArray() }, false );
-	}
-	if( !has( node.metadata, 'rotation.position' ) || get( node.metadata, 'position.dirty' ) ) {
-		let rotationPosition = node.absolutePosition.clone();
-		if( has( node.metadata, 'rotation.offset' ) ) {
-			rotationPosition = rotationPosition.subtract( get( node.metadata, 'rotation.offset' ) as Vector3 );
-		}
-		injectNodeMetadata( node, { 'rotation.position': rotationPosition }, false );
-		injectNodeMetadata( node, { 'position.dirty': false }, false );
-	}
-	node.setAbsolutePosition( get( node.metadata, 'rotation.position' ) );
-	if( node.metadata.rotation ) {
-		node.rotationQuaternion = Quaternion.FromArray( get( node.metadata, 'rotation.initial' ) as [] );
-	}
-	node.rotateAround( Vector3.Zero(), Axis.X, rotation.x );
-	node.rotateAround( Vector3.Zero(), Axis.Y, rotation.y );
-	node.rotateAround( Vector3.Zero(), Axis.Z, rotation.z );
-	node.computeWorldMatrix( true );
-	injectNodeMetadata( node, {
-		'rotation.offset': node.absolutePosition.subtract( get( node.metadata, 'rotation.position' ) as Vector3 )
-	}, false );
-	return node;
-};
-
-/**
- * Attention: this function mutates the position of a node. Keep in mind that there are dependencies to other
- * functions moving nodes around.
- * @param node
- * @param distance
- */
-const moveTransformNode = function( node: TransformNode, distance: Vector3 ): TransformNode {
-	// remember absolute position and reset it before translating
-	if( !has( node.metadata, 'position.initial' ) ) {
-		injectNodeMetadata( node, { 'position.initial': node.absolutePosition.clone() }, false );
-	}
-	let position = get( node.metadata, 'position.initial' ) as Vector3;
-	if( has( node.metadata, 'rotation.offset' ) ) {
-		position = position.add( get( node.metadata, 'rotation.offset' ) as Vector3 );
-	}
-	node.setAbsolutePosition( position.add( distance ) );
-	injectNodeMetadata( node, { 'position.dirty': true }, false );
-	return node;
-};
-
-/**
- * @param node
- * @param material
- * @param deep
- */
-const setMaterial = function( node: TransformNode, material: Material, deep: boolean = true ) {
-	if( node instanceof AbstractMesh ) {
-		node.material = material;
-	}
-	if( deep ) {
-		node.getChildTransformNodes( true ).forEach( child => setMaterial( child, material, 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.apply( Math, coordinates.map( o => o.x ) );
-	const minX = Math.min.apply( Math, coordinates.map( o => o.x ) );
-	const maxY = Math.max.apply( Math, coordinates.map( o => o.y ) );
-	const minY = Math.min.apply( Math, 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,
-	rotateTransformNode,
-	moveTransformNode,
-	setMaterial,
-	setSourceNodeMaterial,
-	setMaterialColor,
-	setMaterialTexture,
-	setMaterialMetallness,
-	setMaterialRoughness,
-	addToHighlightLayer,
-	removeFromHighlightLayer,
-	setReceiveShadows,
-	addToShadowGenerator,
-	removeFromShadowGenerator,
-	getClientRectFromMesh
-};
+import { HighlightLayer } from '@babylonjs/core/Layers/highlightLayer';
+import { Material } from '@babylonjs/core/Materials/material';
+import { PBRMaterial } from '@babylonjs/core/Materials/PBR/pbrMaterial';
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
+import { Color3 } from '@babylonjs/core/Maths/math.color';
+import { 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 { Node } from '@babylonjs/core/node';
+import { Scene } from '@babylonjs/core/scene';
+import { cloneDeep, merge } from 'lodash-es';
+import { DottedPath } from '../classes/dottedPath';
+
+/**
+ * @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 getDottedPathForTransformNode = function( node: TransformNode ): DottedPath {
+	const dottedPath = DottedPath.create( node.name );
+	let _parent = node;
+	while( _parent.parent ) {
+		_parent = _parent.parent as TransformNode;
+		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( deep ) {
+		const children = node.getChildTransformNodes( true );
+		children.forEach( child => {
+			const clonedChild = cloneTransformNode( child, predicate, deep );
+			if( clonedChild ) {
+				clonedChild.parent = clone;
+			}
+		} );
+	}
+	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 _prefix = DottedPath.create( prefix ).addParts([
+			'node',
+			node.uniqueId.toString()
+		]);
+		node.material = node.material.clone( _prefix.path );
+	}
+	if( deep ) {
+		const children = node.getChildTransformNodes( true );
+		children.forEach( child => cloneTransformNodeMaterial( child, prefix, deep ) );
+	}
+	return node;
+};
+
+/**
+ * @param node
+ * @param deep
+ * @param metadata
+ */
+const injectTransformNodeMetadata = function( node: TransformNode, metadata: {}, deep: boolean = true ) {
+	node.metadata = merge( {}, node.metadata, metadata );
+	if( deep ) {
+		const children = node.getChildTransformNodes( true );
+		children.forEach( child => injectTransformNodeMetadata( 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
+ * @param material
+ * @param deep
+ */
+const setMaterial = function( node: TransformNode, material: Material, deep: boolean = true ) {
+	if( node instanceof AbstractMesh ) {
+		node.material = material;
+	}
+	if( deep ) {
+		node.getChildTransformNodes( true ).forEach( child => setMaterial( child, material, 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 )
+		);
+	}
+};
+
+/**
+ * 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.apply( Math, coordinates.map( o => o.x ) );
+	const minX = Math.min.apply( Math, coordinates.map( o => o.x ) );
+	const maxY = Math.max.apply( Math, coordinates.map( o => o.y ) );
+	const minY = Math.min.apply( Math, 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 {
+	mapToDottedNodes,
+	getDottedPathForTransformNode,
+	cloneTransformNode,
+	cloneTransformNodeMaterial,
+	injectTransformNodeMetadata,
+	assertTransformNode,
+	activateTransformNode,
+	deactivateTransformNode,
+	setMaterial,
+	setSourceNodeMaterial,
+	setMaterialColor,
+	setMaterialTexture,
+	setMaterialMetallness,
+	setMaterialRoughness,
+	addToHighlightLayer,
+	removeFromHighlightLayer,
+	getClientRectFromMesh
+};