@combeenation/3d-viewer 3.1.1-alpha7 → 3.1.2

package/src/api/classes/element.ts

@@ -1,606 +1,608 @@
-import { HighlightLayer } from '@babylonjs/core/Layers/highlightLayer';
-import { Material } from '@babylonjs/core/Materials/material';
-import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
-import { Axis, Space } from '@babylonjs/core/Maths/math.axis';
-import { Color3 } from '@babylonjs/core/Maths/math.color';
-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 { Texture } from '@babylonjs/core/Materials/Textures/texture';
-import { cloneDeep, concat, get, isArray, merge, union } from 'lodash-es';
-import {
-	activateTransformNode as activate,
-	addToHighlightLayer,
-	assertTransformNode,
-	cloneTransformNode,
-	cloneTransformNodeMaterial,
-	deactivateTransformNode as deactivate,
-	getClientRectFromMesh,
-	injectTransformNodeMetadata,
-	mapToDottedNodes,
-	removeFromHighlightLayer,
-	setMaterial,
-	setMaterialColor,
-	setMaterialMetallness,
-	setMaterialRoughness,
-	setMaterialTexture
-} from '../util/babylonHelper';
-import { createImageUrlFromSvg, mergeMaps } from '../util/resourceHelper';
-import { DottedPath } from './dottedPath';
-import { ElementParameterizable } from './elementParameterizable';
-import { Event } from './event';
-import { Parameter } from './parameter';
-import { Variant } from './variant';
-
-/**
- * An {@link Element} of a {@link Variant}. Acts as a container for diverse definitions. Lives only in the context of a
- * {@link Variant}.
- * 
- * When used in typings, refer to via its alias {@link VariantElement} to prevent name clashes with the web APIs
- * [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) class
- */
-export class Element extends ElementParameterizable {
-
-	protected readonly _dottedNodes: Map<DottedPath, TransformNode> = new Map();
-
-	protected readonly _parameterObservers: Map<string, ParameterObserver[]> = new Map();
-
-	protected _highlightLayer?: HighlightLayer;
-
-	protected _paintableTextureId: number = 0;
-
-	public readonly nodes: TransformNode[] = [];
-
-	/**
-	 * Constructor.
-	 */
-	public constructor( public readonly variant: Variant,
-	                    public readonly name: string ) {
-		super();
-		if ( process.env.NODE_ENV?.toLowerCase().includes('dev')) {
-			this.assertPathDefinitions();
-		}
-		const nodes = this.variant.inheritedNodes.map(
-			node => cloneTransformNode( node, this.filterNode.bind(this) )
-		);
-		this.nodes = nodes.filter( node => !!node ) as TransformNode[];
-		this._dottedNodes = mapToDottedNodes<TransformNode>(
-			this.nodes,
-			node => node instanceof TransformNode
-		);
-		this.addParameterObservers();
-	}
-
-	/**
-	 * The {@link DottedPath} in the built tree of {@link Element}s.
-	 * E.g. "_.top-1.sub-2.sub-sub-3.el-1"
-	 */
-	get dottedPath(): DottedPath {
-		return DottedPath.create( this.variant.dottedPath ).addPart( this.name );
-	}
-
-	/**
-	 * The id representing a {@link DottedPath}.
-	 */
-	get id(): string {
-		const dottedPath = DottedPath.create( this.dottedPath );
-		dottedPath.shiftPart();  // remove root
-		return dottedPath.path;
-	}
-
-	/**
-	 * The {@link ElementDefinition} of the {@link Element}.
-	 */
-	get definition(): ElementDefinition {
-		const definition = this.variant.structureJson.elements![this.name];
-		if( isArray( definition ) ) {
-			return {
-				paths: {
-					include: definition
-				}
-			} as ElementDefinition;
-		}
-		return definition as ElementDefinition;
-	}
-
-	/**
-	 * The {@link PathDefinitions} of the {@link Element}.
-	 */
-	get pathDefinitions(): PathDefinitions {
-		return this.definition.paths;
-	}
-
-	/**
-	 * The {@link TraceableDefinitions} of the {@link Element}.
-	 */
-	get traceableDefinitions(): TraceableDefinitions {
-		return this.definition.traceables || {};
-	}
-
-	/**
-	 * The {@link PaintableDefinition} of the {@link Element}.
-	 */
-	get paintableDefinitions(): PaintableDefinitions {
-		return this.definition.paintables || {};
-	}
-
-	/**
-	 * The inherited {@link ParameterBag}.
-	 * Merges the {@link Variant}'s parameters and those from the {@link Element}.
-	 */
-	get inheritedParameters(): ParameterBag {
-		return merge( {}, this.variant.inheritedParameters, this.parameters );
-	}
-
-	/**
-	 * @protected
-	 */
-	set highlightLayer(layer: HighlightLayer | undefined) {
-		this._highlightLayer = layer;
-	}
-
-	get highlightLayer(): HighlightLayer | undefined {
-		return this._highlightLayer;
-	}
-
-	/**
-	 * Destroys this {@link Element} and dispose all nodes.
-	 */
-	public destroy(): Element {
-		this.nodes.forEach( node => {
-			node.dispose();
-		} );
-		return this;
-	}
-
-	/**
-	 * Gets a node by its {@link DottedPath}.
-	 */
-	public getNode( dottedPath: DottedPathArgument ): TransformNode {
-		const _dottedPath = DottedPath.create( dottedPath );
-		const keys = Array.from( this._dottedNodes.keys() ).map( dp => dp.path );
-		const values = Array.from( this._dottedNodes.values() );
-		const node = values[keys.indexOf( _dottedPath.path )];
-		if( !node ) {
-			throw new Error( `Node with path "${_dottedPath.path}" does not exist for element "${this.id}".` );
-		}
-		return node;
-	}
-
-	/**
-	 * Gets a mesh by its {@link DottedPath}.
-	 */
-	public async getMesh( dottedPath: DottedPathArgument ): Promise<Mesh|null> {
-		const node = await this.getNode( dottedPath );
-		if( node instanceof Mesh ) {
-			return node;
-		}
-		return null;
-	}
-
-	/**
-	 * Gets a {@link PaintableDefinition} by its name.
-	 */
-	public getPaintableDefinition( name: string ): PaintableDefinition {
-		if( !this.paintableDefinitions || !this.paintableDefinitions[name] ) {
-			throw new Error( `No paintable "${name}" defined for element "${this.id}".` );
-		}
-		return this.paintableDefinitions[name];
-	}
-
-	/**
-	 * Gets a {@link TraceableDefinition} by its name.
-	 */
-	public getTraceableDefinition( name: string ): TraceableDefinition {
-		if( !this.traceableDefinitions || !this.traceableDefinitions[name] ) {
-			throw new Error( `No traceable "${name}" defined to add observer in element "${this.id}".` );
-		}
-		return this.traceableDefinitions[name];
-	}
-
-	/**
-	 * Gets the paintable Node by its name.
-	 */
-	public getPaintableNode( name: string ): TransformNode {
-		return this.getNode( this.getPaintableDefinition( name ).path );
-	}
-
-	/**
-	 * Gets the traceable Node by its name.
-	 */
-	public getTraceableNode( name: string ): TransformNode {
-		return this.getNode( this.getTraceableDefinition( name ).path );
-	}
-
-	/**
-	 * Places the given {@link ParameterBag} in the {@link Element}'s parameters, replaces all patterns in the
-	 * {@link StructureJson} and broadcasts all {@link ParameterObserver}s.
-	 *
-	 * @emit {@link Event.ELEMENT_PARAMETER_COMMITTED}
-	 */
-	public async commitParameters( parameters?: ParameterBag ): Promise<Element> {
-		if( !parameters ) {
-			parameters = {};
-		}
-		const oldParameters = cloneDeep( this.parameters );
-		merge( this.parameters, parameters );
-		// handle parameter observers
-		let observerPromises: Promise<void | ParameterObserver>[] = [];
-		for( const parameter in this.parameters ) {
-			const oldParameterValue = oldParameters[parameter];
-			const newParameterValue = this.parameters[parameter];
-			this.variant.assertParameter( this.variant.inheritedParameterDeclaration, parameter, newParameterValue );
-			if( oldParameterValue === newParameterValue ) {
-				continue;
-			}
-			// parameter changed
-			const parameterObservers = mergeMaps( this._parameterObservers, this.parameterObservers );
-			if( parameterObservers.has( parameter ) ) {
-				const observers = parameterObservers.get( parameter )!;
-				observerPromises = concat(observerPromises, observers.map( observer => {
-					const observerResult = observer( this, oldParameterValue, newParameterValue );
-					return Promise.resolve( observerResult ).then( () => {
-						this.broadcastEvent( Event.ELEMENT_PARAMETER_COMMITTED,
-							this, parameter, oldParameterValue, newParameterValue );
-					} );
-				} ) );
-			}
-		}
-		await Promise.all( observerPromises );
-		return this;
-	}
-
-	/**
-	 * Adds an observer function for camera matrix changes.
-	 * The `observer` gets 2 parameters: the `AbstractMesh` and a `ClientRect` object.
-	 */
-	public addTraceableObserver( traceable: string, observer: CallableFunction, payload?: any ): Element {
-		if( payload && !(payload instanceof HTMLElement) ) {
-			throw new Error( `Payload for camera observer must be an instance of "HTMLElement" in element "${this.id}".` );
-		}
-		if( !this.traceableDefinitions || !this.traceableDefinitions[traceable] ) {
-			throw new Error( `No traceable "${traceable}" defined to add observer in element "${this.id}".` );
-		}
-		const node = this.getTraceableNode( traceable );
-		if( !(node instanceof AbstractMesh) ) {
-			throw new Error( `The path must be an instance of "AbstractMesh" for camera observer in element "${this.id}".` );
-		}
-		this.variant.viewer.sceneManager.activeCamera.onViewMatrixChangedObservable.add(
-			( eventData, eventState ) => {
-				const position = getClientRectFromMesh( node, this.variant.viewer.scene, this.variant.viewer.canvas );
-				if( payload ) {
-					payload.style.top = `${position.top}px`;
-					payload.style.left = `${position.left}px`;
-				}
-				observer( node, position );
-			}
-		);
-		return this;
-	}
-
-	/**
-	 * Draws a image onto a `paintable` defined via {@link PaintableDefinition}.
-	 */
-	public async drawPaintable( paintable: string, imageSource: string ): Promise<Element> {
-		const node = this.getPaintableNode( paintable );
-		if( !(node instanceof AbstractMesh) ) {
-			throw new Error( `The path must be an instance of "AbstractMesh" for paintable "${paintable}" ` +
-				`in element "${this.id}".` );
-		}
-		if( node.material && !get( node.metadata, 'dirty.material' ) ) {
-			cloneTransformNodeMaterial( node );
-		}
-		if( !node.material ) {
-			node.material = new StandardMaterial( `${this.id}.${paintable}.material`, this.variant.viewer.scene );
-		}
-		node.material.transparencyMode = Material.MATERIAL_ALPHATESTANDBLEND;
-		if( !get( node.metadata, 'dirty.material.texture' ) ) {
-			// inject initial value and mark as dirty
-			injectTransformNodeMetadata( node, { dirty: { material: { texture: true	} } }, false );
-		}
-
-		await new Promise<void>(resolve => {
-			const paintableTexture = Texture.CreateFromBase64String(
-				imageSource,
-				`${this.id}.${paintable}.texture.${this._paintableTextureId}`,
-				this.variant.viewer.scene,
-				undefined,
-				false,
-				undefined,
-				() => {
-					setMaterialTexture( node, paintableTexture, false );
-					resolve();
-				}
-			);
-
-			// NOTE: Paintable texture need an individual id, otherwise the already existing texture on this id does not get overwritten
-			// Maybe think of a disposal logic here in the future
-			this._paintableTextureId++;
-		});
-		
-		return this;
-	}
-
-	/**
-	 * Draws a SVG string onto a `paintable` defined via {@link PaintableDefinition}.
-	 */
-	public async drawPaintableFromSvg( paintable: string, svgSource: string ): Promise<Element> {
-		const imageUrl = await createImageUrlFromSvg( svgSource );
-		return this.drawPaintable( paintable, imageUrl );
-	}
-
-	/**
-	 * Draws an Image from source (URL/URI) onto a `paintable` defined via {@link PaintableDefinition}.
-	 */
-	public async drawPaintableFromImgSrc( paintable: string, imgSource: string ): Promise<Element> {
-		return this.drawPaintable( paintable, imgSource );
-	}
-
-	/**
-	 * Adds the default {@link ParameterObserver}s which are called every time {@link commitParameters} is called.
-	 */
-	protected addParameterObservers(): Element {
-		this._parameterObservers.set( Parameter.VISIBLE, [
-			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				let visible;
-				try {
-					visible = Parameter.parseBoolean( newValue );
-				} catch( e ) {
-					return;
-				}
-				if( visible === true ) {
-					element.nodes.forEach( node => {
-						injectTransformNodeMetadata( node, { visibility: node.isEnabled() } );
-						activate( node );
-					} );
-				} else if( visible === false ) {
-					element.nodes.forEach( node => {
-						injectTransformNodeMetadata( node, { visibility: node.isEnabled() } );
-						deactivate( node );
-					} );
-				}
-			}
-		] );
-		this._parameterObservers.set( Parameter.SCALING, [
-			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				// we have to deal just with root nodes here due to relative impacts in a node tree
-				element.nodes.forEach( node => node.scaling = Parameter.parseScaling( newValue ) );
-			}
-		] );
-		this._parameterObservers.set( Parameter.MATERIAL, [
-			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				const material = element.variant.getMaterial( newValue.toString() );
-				element.nodes.forEach( node => {
-					assertTransformNode(node, (node: TransformNode) => {
-						if( node instanceof InstancedMesh ) {
-							throw new Error( `Changing parameter "${Parameter.MATERIAL}" ` +
-								`of an InstancedMesh is not supported. ` +
-								`Tried to change node "${node.id}" on element "${element.id}".` );
-						}
-					});
-					setMaterial( node, material );
-				} );
-			}
-		] );
-		this._parameterObservers.set( Parameter.MATERIAL_COLOR, [
-			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				const color = Parameter.parseColor( newValue );
-				element.nodes.forEach( node => {
-					assertTransformNode(node, (node: TransformNode) => {
-						if( node instanceof InstancedMesh ) {
-							throw new Error( `Changing parameter "${Parameter.MATERIAL_COLOR}" ` +
-								`of an InstancedMesh is not supported. ` +
-								`Tried to change node "${node.id}" on element "${element.id}".` );
-						}
-					});
-					if( !get( node.metadata, 'dirty.material' ) ) {
-						cloneTransformNodeMaterial( node );
-					}
-					if( !get( node.metadata, 'dirty.material.color' ) ) {
-						// inject initial value and mark as dirty
-						injectTransformNodeMetadata( node, { dirty: { material: { color: oldValue } } } );
-					}
-					setMaterialColor( node, color );
-				} );
-			}
-		] );
-		this._parameterObservers.set( Parameter.MATERIAL_METALLNESS, [
-			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				const metallness = Parameter.parseNumber( newValue );
-				element.nodes.forEach( node => {
-					assertTransformNode(node, (node: TransformNode) => {
-						if( node instanceof InstancedMesh ) {
-							throw new Error( `Changing parameter "${Parameter.MATERIAL_METALLNESS}" ` +
-								`of an InstancedMesh is not supported. ` +
-								`Tried to change node "${node.id}" on element "${element.id}".` );
-						}
-					});
-					if( !get( node.metadata, 'dirty.material' ) ) {
-						cloneTransformNodeMaterial( node );
-					}
-					if( !get( node.metadata, 'dirty.material.metallness' ) ) {
-						// inject initial value and mark as dirty
-						injectTransformNodeMetadata( node, { dirty: { material: { metallness: oldValue } } } );
-					}
-					setMaterialMetallness( node, metallness );
-				} );
-			}
-		] );
-		this._parameterObservers.set( Parameter.MATERIAL_ROUGHNESS, [
-			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				const roughness = Parameter.parseNumber( newValue );
-				element.nodes.forEach( node => {
-					assertTransformNode(node, (node: TransformNode) => {
-						if( node instanceof InstancedMesh ) {
-							throw new Error( `Changing parameter "${Parameter.MATERIAL_ROUGHNESS}" ` +
-								`of an InstancedMesh is not supported. ` +
-								`Tried to change node "${node.id}" on element "${element.id}".` );
-						}
-					});
-					if( !get( node.metadata, 'dirty.material' ) ) {
-						cloneTransformNodeMaterial( node );
-					}
-					if( !get( node.metadata, 'dirty.material.roughness' ) ) {
-						// inject initial value and mark as dirty
-						injectTransformNodeMetadata( node, { dirty: { material: { roughness: oldValue } } } );
-					}
-					setMaterialRoughness( node, roughness );
-				} );
-			}
-		] );
-		this._parameterObservers.set( Parameter.HIGHLIGHT_COLOR, [
-			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				// trigger Parameter.HIGHLIGHTED observers
-				this._parameterObservers.get( Parameter.HIGHLIGHTED )?.forEach( observer => {
-					observer( element, !!element.highlighted, !!element.highlighted );
-				} );
-			}
-		] );
-		this._parameterObservers.set( Parameter.HIGHLIGHT_ENABLED, [
-			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				let curr;
-				try {
-					curr = Parameter.parseBoolean( newValue );
-				} catch( e ) {
-					return;
-				}
-				switch( curr ) {
-					case true:
-						if( element._highlightLayer ) {
-							break;
-						}
-						element.highlightLayer = new HighlightLayer(
-							DottedPath.create( element.id ).addPart( 'highlight' ).path,
-							element.variant.viewer.scene
-						);
-						break;
-					case false:
-						element.highlightLayer?.dispose();
-						break;
-				}
-			}
-		] );
-		this._parameterObservers.set( Parameter.HIGHLIGHTED, [
-			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				if( !element.inheritedParameters[Parameter.HIGHLIGHT_ENABLED] ) {
-					return;
-				}
-				// trigger Parameter.HIGHLIGHT_ENABLED observers to ensure HighlightLayer
-				this._parameterObservers.get( Parameter.HIGHLIGHT_ENABLED )?.forEach( observer => {
-					observer( element, this.parameters[Parameter.HIGHLIGHT_ENABLED], true );
-				} );
-				let highlighted;
-				try {
-					highlighted = Parameter.parseBoolean( newValue );
-				} catch( e ) {
-					return;
-				}
-				// Add/Remove meshes to previously created highlight layers.
-				if( highlighted === true ) {
-					element.nodes.forEach( node => {
-						assertTransformNode(node, (node: TransformNode) => {
-							if( node instanceof InstancedMesh ) {
-								throw new Error( `Changing parameter "${Parameter.HIGHLIGHTED}" ` +
-									`of an InstancedMesh is not supported. ` +
-									`Tried to change node "${node.id}" on element "${element.id}".` );
-							}
-						});
-						let color = Color3.Green();
-						if( element.inheritedParameters[Parameter.HIGHLIGHT_COLOR] ) {
-							color = Parameter.parseColor( element.inheritedParameters[Parameter.HIGHLIGHT_COLOR] );
-						}
-						if ( typeof element._highlightLayer !== "undefined" ) {
-							addToHighlightLayer( element._highlightLayer, color, node );
-						}
-					} );
-				} else if( highlighted === false ) {
-					element.nodes.forEach( node => {
-						if ( typeof element._highlightLayer !== "undefined" ) {
-							removeFromHighlightLayer( element._highlightLayer, node );
-						}
-					} );
-				}
-			}
-		] );
-		this._parameterObservers.set( Parameter.POSITION, [
-			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				// we have to deal just with root nodes here due to relative impacts in a node tree
-				element.nodes.forEach( node => {
-					// remember absolute position and reset it before translating
-					if( !get( node.metadata, 'position' ) ) {
-						node.metadata.position = node.absolutePosition.clone();
-					}
-					node.setAbsolutePosition( node.metadata.position );
-					// move
-					const distance = Parameter.parseVector( newValue );
-					node.translate( Axis.X, distance.x, Space.WORLD );
-					node.translate( Axis.Y, distance.y, Space.WORLD );
-					node.translate( Axis.Z, distance.z, Space.WORLD );
-				} );
-			}
-		] );
-		this._parameterObservers.set( Parameter.ROTATION, [
-			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				// we have to deal just with root nodes here due to relative impacts in a node tree
-				element.nodes.forEach( node => {
-					// remember absolute rotation and reset it before translating
-					if(!get( node.metadata, 'rotation' ) ) {
-						node.metadata.rotation = node.rotation.clone();
-					}
-					node.rotation = node.metadata.rotation;
-					// rotate
-					const rotation = Parameter.parseRotation( newValue );
-					node.rotate( Axis.X, rotation.x, Space.WORLD );
-					node.rotate( Axis.Y, rotation.y, Space.WORLD );
-					node.rotate( Axis.Z, rotation.z, Space.WORLD );
-				} );
-			}
-		] );
-		return this;
-	}
-
-	/**
-	 * Filter for nodes that are not defined or excluded in the `pathDefinitions`.
-	 */
-	protected filterNode( node: TransformNode ): boolean {
-		let includeTokens: string[] = [];
-		this.pathDefinitions.include.forEach( dottedPath => {
-			includeTokens = union( includeTokens, DottedPath.create( dottedPath ).leafTokens );
-		} );
-		const shallKeep = ( dp: DottedPath ) => {
-			const isDirectlyIncluded = !!includeTokens.find( _dp => _dp === dp.path );
-			const isSubOfIncluded = !!this.pathDefinitions.include.find( _dp =>  {
-				return dp.path.startsWith( `${_dp}${DottedPath.DELIMITER}` );
-			} );
-			return isDirectlyIncluded || isSubOfIncluded;
-		};
-		const shallExclude = ( dp: DottedPath ) => {
-			if( !this.pathDefinitions.exclude ) {
-				return false;
-			}
-			return !!this.pathDefinitions.exclude.find( _dp => dp.path === _dp );
-		};
-		return shallKeep( node.metadata.dottedPath ) && !shallExclude( node.metadata.dottedPath );
-	}
-
-	/**
-	 * Asserts whether all {@link pathDefinitions} link to a valid `Node` path.
-	 * @protected
-	 */
-	protected assertPathDefinitions() {
-		const dottedNodes = this.variant.inheritedDottedNodes;
-		if( dottedNodes.size === 0 ) {
-			throw new Error( `There are no mapped nodes for element "${this.id}".` );
-		}
-		const include = this.pathDefinitions.include.map( path => DottedPath.create( path ).path );
-		const exclude = this.pathDefinitions.exclude?.map( path => DottedPath.create( path ).path );
-		const keys = Array.from( dottedNodes.keys() ).map( dottedPath => dottedPath.path );
-		union<string>( include, exclude ).forEach( path => {
-			if( keys.indexOf( path ) === -1 ) {
-				throw new Error( `Node with path "${path}" does not exist for element "${this.id}".` );
-			}
-		} );
-	}
-
-}
+import { HighlightLayer } from '@babylonjs/core/Layers/highlightLayer';
+import { Material } from '@babylonjs/core/Materials/material';
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
+import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
+import { Axis, Space } from '@babylonjs/core/Maths/math.axis';
+import { Color3 } from '@babylonjs/core/Maths/math.color';
+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 { cloneDeep, concat, get, isArray, isNumber, isPlainObject, merge, union } from 'lodash-es';
+import {
+	activateTransformNode as activate,
+	addToHighlightLayer,
+	assertTransformNode,
+	cloneTransformNode,
+	cloneTransformNodeMaterial,
+	deactivateTransformNode as deactivate,
+	getClientRectFromMesh,
+	injectTransformNodeMetadata,
+	mapToDottedNodes,
+	removeFromHighlightLayer,
+	setMaterial,
+	setMaterialColor,
+	setMaterialMetallness,
+	setMaterialRoughness,
+	setMaterialTexture
+} from '../util/babylonHelper';
+import { createImageBitmapFromImgSrc, createImageBitmapFromSvg, mergeMaps } from '../util/resourceHelper';
+import { DottedPath } from './dottedPath';
+import { ElementParameterizable } from './elementParameterizable';
+import { Event } from './event';
+import { Parameter } from './parameter';
+import { Variant } from './variant';
+
+/**
+ * An {@link Element} of a {@link Variant}. Acts as a container for diverse definitions. Lives only in the context of a
+ * {@link Variant}.
+ * 
+ * When used in typings, refer to via its alias {@link VariantElement} to prevent name clashes with the web APIs
+ * [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) class
+ */
+export class Element extends ElementParameterizable {
+
+	protected readonly _dottedNodes: Map<DottedPath, TransformNode> = new Map();
+
+	protected readonly _parameterObservers: Map<string, ParameterObserver[]> = new Map();
+
+	protected _highlightLayer?: HighlightLayer;
+
+	public readonly nodes: TransformNode[] = [];
+
+	/**
+	 * Constructor.
+	 */
+	public constructor( public readonly variant: Variant,
+	                    public readonly name: string ) {
+		super();
+		if ( process.env.NODE_ENV?.toLowerCase().includes('dev')) {
+			this.assertPathDefinitions();
+		}
+		const nodes = this.variant.inheritedNodes.map(
+			node => cloneTransformNode( node, this.filterNode.bind(this) )
+		);
+		this.nodes = nodes.filter( node => !!node ) as TransformNode[];
+		this._dottedNodes = mapToDottedNodes<TransformNode>(
+			this.nodes,
+			node => node instanceof TransformNode
+		);
+		this.addParameterObservers();
+	}
+
+	/**
+	 * The {@link DottedPath} in the built tree of {@link Element}s.
+	 * E.g. "_.top-1.sub-2.sub-sub-3.el-1"
+	 */
+	get dottedPath(): DottedPath {
+		return DottedPath.create( this.variant.dottedPath ).addPart( this.name );
+	}
+
+	/**
+	 * The id representing a {@link DottedPath}.
+	 */
+	get id(): string {
+		const dottedPath = DottedPath.create( this.dottedPath );
+		dottedPath.shiftPart();  // remove root
+		return dottedPath.path;
+	}
+
+	/**
+	 * The {@link ElementDefinition} of the {@link Element}.
+	 */
+	get definition(): ElementDefinition {
+		const definition = this.variant.structureJson.elements![this.name];
+		if( isArray( definition ) ) {
+			return {
+				paths: {
+					include: definition
+				}
+			} as ElementDefinition;
+		}
+		return definition as ElementDefinition;
+	}
+
+	/**
+	 * The {@link PathDefinitions} of the {@link Element}.
+	 */
+	get pathDefinitions(): PathDefinitions {
+		return this.definition.paths;
+	}
+
+	/**
+	 * The {@link TraceableDefinitions} of the {@link Element}.
+	 */
+	get traceableDefinitions(): TraceableDefinitions {
+		return this.definition.traceables || {};
+	}
+
+	/**
+	 * The {@link PaintableDefinition} of the {@link Element}.
+	 */
+	get paintableDefinitions(): PaintableDefinitions {
+		return this.definition.paintables || {};
+	}
+
+	/**
+	 * The inherited {@link ParameterBag}.
+	 * Merges the {@link Variant}'s parameters and those from the {@link Element}.
+	 */
+	get inheritedParameters(): ParameterBag {
+		return merge( {}, this.variant.inheritedParameters, this.parameters );
+	}
+
+	/**
+	 * @protected
+	 */
+	set highlightLayer(layer: HighlightLayer | undefined) {
+		this._highlightLayer = layer;
+	}
+
+	get highlightLayer(): HighlightLayer | undefined {
+		return this._highlightLayer;
+	}
+
+	/**
+	 * Destroys this {@link Element} and dispose all nodes.
+	 */
+	public destroy(): Element {
+		this.nodes.forEach( node => {
+			node.dispose();
+		} );
+		return this;
+	}
+
+	/**
+	 * Gets a node by its {@link DottedPath}.
+	 */
+	public getNode( dottedPath: DottedPathArgument ): TransformNode {
+		const _dottedPath = DottedPath.create( dottedPath );
+		const keys = Array.from( this._dottedNodes.keys() ).map( dp => dp.path );
+		const values = Array.from( this._dottedNodes.values() );
+		const node = values[keys.indexOf( _dottedPath.path )];
+		if( !node ) {
+			throw new Error( `Node with path "${_dottedPath.path}" does not exist for element "${this.id}".` );
+		}
+		return node;
+	}
+
+	/**
+	 * Gets a mesh by its {@link DottedPath}.
+	 */
+	public async getMesh( dottedPath: DottedPathArgument ): Promise<Mesh|null> {
+		const node = await this.getNode( dottedPath );
+		if( node instanceof Mesh ) {
+			return node;
+		}
+		return null;
+	}
+
+	/**
+	 * Gets a {@link PaintableDefinition} by its name.
+	 */
+	public getPaintableDefinition( name: string ): PaintableDefinition {
+		if( !this.paintableDefinitions || !this.paintableDefinitions[name] ) {
+			throw new Error( `No paintable "${name}" defined for element "${this.id}".` );
+		}
+		return this.paintableDefinitions[name];
+	}
+
+	/**
+	 * Gets a {@link TraceableDefinition} by its name.
+	 */
+	public getTraceableDefinition( name: string ): TraceableDefinition {
+		if( !this.traceableDefinitions || !this.traceableDefinitions[name] ) {
+			throw new Error( `No traceable "${name}" defined to add observer in element "${this.id}".` );
+		}
+		return this.traceableDefinitions[name];
+	}
+
+	/**
+	 * Gets the paintable Node by its name.
+	 */
+	public getPaintableNode( name: string ): TransformNode {
+		return this.getNode( this.getPaintableDefinition( name ).path );
+	}
+
+	/**
+	 * Gets the traceable Node by its name.
+	 */
+	public getTraceableNode( name: string ): TransformNode {
+		return this.getNode( this.getTraceableDefinition( name ).path );
+	}
+
+	/**
+	 * Places the given {@link ParameterBag} in the {@link Element}'s parameters, replaces all patterns in the
+	 * {@link StructureJson} and broadcasts all {@link ParameterObserver}s.
+	 *
+	 * @emit {@link Event.ELEMENT_PARAMETER_COMMITTED}
+	 */
+	public async commitParameters( parameters?: ParameterBag ): Promise<Element> {
+		if( !parameters ) {
+			parameters = {};
+		}
+		const oldParameters = cloneDeep( this.parameters );
+		merge( this.parameters, parameters );
+		// handle parameter observers
+		let observerPromises: Promise<void | ParameterObserver>[] = [];
+		for( const parameter in this.parameters ) {
+			const oldParameterValue = oldParameters[parameter];
+			const newParameterValue = this.parameters[parameter];
+			this.variant.assertParameter( this.variant.inheritedParameterDeclaration, parameter, newParameterValue );
+			if( oldParameterValue === newParameterValue ) {
+				continue;
+			}
+			// parameter changed
+			const parameterObservers = mergeMaps( this._parameterObservers, this.parameterObservers );
+			if( parameterObservers.has( parameter ) ) {
+				const observers = parameterObservers.get( parameter )!;
+				observerPromises = concat(observerPromises, observers.map( observer => {
+					const observerResult = observer( this, oldParameterValue, newParameterValue );
+					return Promise.resolve( observerResult ).then( () => {
+						this.broadcastEvent( Event.ELEMENT_PARAMETER_COMMITTED,
+							this, parameter, oldParameterValue, newParameterValue );
+					} );
+				} ) );
+			}
+		}
+		await Promise.all( observerPromises );
+		return this;
+	}
+
+	/**
+	 * Adds an observer function for camera matrix changes.
+	 * The `observer` gets 2 parameters: the `AbstractMesh` and a `ClientRect` object.
+	 */
+	public addTraceableObserver( traceable: string, observer: CallableFunction, payload?: any ): Element {
+		if( payload && !(payload instanceof HTMLElement) ) {
+			throw new Error( `Payload for camera observer must be an instance of "HTMLElement" in element "${this.id}".` );
+		}
+		if( !this.traceableDefinitions || !this.traceableDefinitions[traceable] ) {
+			throw new Error( `No traceable "${traceable}" defined to add observer in element "${this.id}".` );
+		}
+		const node = this.getTraceableNode( traceable );
+		if( !(node instanceof AbstractMesh) ) {
+			throw new Error( `The path must be an instance of "AbstractMesh" for camera observer in element "${this.id}".` );
+		}
+		this.variant.viewer.sceneManager.activeCamera.onViewMatrixChangedObservable.add(
+			( eventData, eventState ) => {
+				const position = getClientRectFromMesh( node, this.variant.viewer.scene, this.variant.viewer.canvas );
+				if( payload ) {
+					payload.style.top = `${position.top}px`;
+					payload.style.left = `${position.left}px`;
+				}
+				observer( node, position );
+			}
+		);
+		return this;
+	}
+
+	/**
+	 * Draws a `ImageBitmap` or `OffscreenCanvas` onto a `paintable` defined via {@link PaintableDefinition}.
+	 */
+	public drawPaintable( paintable: string, imageSource: CanvasImageSource ): Element {
+		const paintableDefinition = this.getPaintableDefinition( paintable );
+		const node = this.getPaintableNode( paintable );
+		if( !(node instanceof AbstractMesh) ) {
+			throw new Error( `The path must be an instance of "AbstractMesh" for paintable "${paintable}" ` +
+				`in element "${this.id}".` );
+		}
+		if( node.material && !get( node.metadata, 'dirty.material' ) ) {
+			cloneTransformNodeMaterial( node );
+		}
+		if( !node.material ) {
+			node.material = new StandardMaterial( `${this.id}.${paintable}.material`, this.variant.viewer.scene );
+		}
+		node.material.transparencyMode = Material.MATERIAL_ALPHATESTANDBLEND;
+		if( !get( node.metadata, 'dirty.material.texture' ) ) {
+			// inject initial value and mark as dirty
+			injectTransformNodeMetadata( node, { dirty: { material: { texture: true	} } } );
+		}
+		const widthAndHeight = {
+			width: imageSource.width,
+			height: imageSource.height
+		};
+		if( isNumber( paintableDefinition.textureOptions ) ) {
+			widthAndHeight.width = paintableDefinition.textureOptions;
+			widthAndHeight.height = paintableDefinition.textureOptions;
+		} else if( isPlainObject( paintableDefinition.textureOptions ) ) {
+			widthAndHeight.width = paintableDefinition.textureOptions.width;
+			widthAndHeight.height = paintableDefinition.textureOptions.height;
+		}
+		const texture = new DynamicTexture(
+			`${this.id}.${paintable}.texture`,
+			widthAndHeight,
+			this.variant.viewer.scene,
+			false
+		);
+		setMaterialTexture( node, texture, false );
+		const ctx = texture.getContext();
+		// flip texture context horizontal with translate and scale
+		ctx.drawImage( imageSource, 0, 0);
+		texture.update( false );
+		return this;
+	}
+
+	/**
+	 * Draws a SVG string onto a `paintable` defined via {@link PaintableDefinition}.
+	 */
+	public async drawPaintableFromSvg( paintable: string, svgSource: string ): Promise<Element> {
+		const source = await createImageBitmapFromSvg( svgSource );
+		return this.drawPaintable( paintable, source );
+	}
+
+	/**
+	 * Draws an Image from source (URL/URI) onto a `paintable` defined via {@link PaintableDefinition}.
+	 */
+	public async drawPaintableFromImgSrc( paintable: string, imgSource: string ): Promise<Element> {
+		const source = await createImageBitmapFromImgSrc( imgSource );
+		return this.drawPaintable( paintable, source );
+	}
+
+	/**
+	 * Adds the default {@link ParameterObserver}s which are called every time {@link commitParameters} is called.
+	 */
+	protected addParameterObservers(): Element {
+		this._parameterObservers.set( Parameter.VISIBLE, [
+			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				let visible;
+				try {
+					visible = Parameter.parseBoolean( newValue );
+				} catch( e ) {
+					return;
+				}
+				if( visible === true ) {
+					element.nodes.forEach( node => {
+						injectTransformNodeMetadata( node, { visibility: node.isEnabled() } );
+						activate( node );
+					} );
+				} else if( visible === false ) {
+					element.nodes.forEach( node => {
+						injectTransformNodeMetadata( node, { visibility: node.isEnabled() } );
+						deactivate( node );
+					} );
+				}
+			}
+		] );
+		this._parameterObservers.set( Parameter.SCALING, [
+			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				// we have to deal just with root nodes here due to relative impacts in a node tree
+				element.nodes.forEach( node => node.scaling = Parameter.parseScaling( newValue ) );
+			}
+		] );
+		this._parameterObservers.set( Parameter.MATERIAL, [
+			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				const material = element.variant.getMaterial( newValue.toString() );
+				element.nodes.forEach( node => {
+					assertTransformNode(node, (node: TransformNode) => {
+						if( node instanceof InstancedMesh ) {
+							throw new Error( `Changing parameter "${Parameter.MATERIAL}" ` +
+								`of an InstancedMesh is not supported. ` +
+								`Tried to change node "${node.id}" on element "${element.id}".` );
+						}
+					});
+					setMaterial( node, material );
+				} );
+			}
+		] );
+		this._parameterObservers.set( Parameter.MATERIAL_COLOR, [
+			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				const color = Parameter.parseColor( newValue );
+				element.nodes.forEach( node => {
+					assertTransformNode(node, (node: TransformNode) => {
+						if( node instanceof InstancedMesh ) {
+							throw new Error( `Changing parameter "${Parameter.MATERIAL_COLOR}" ` +
+								`of an InstancedMesh is not supported. ` +
+								`Tried to change node "${node.id}" on element "${element.id}".` );
+						}
+					});
+					if( !get( node.metadata, 'dirty.material' ) ) {
+						cloneTransformNodeMaterial( node );
+					}
+					if( !get( node.metadata, 'dirty.material.color' ) ) {
+						// inject initial value and mark as dirty
+						injectTransformNodeMetadata( node, { dirty: { material: { color: oldValue } } } );
+					}
+					setMaterialColor( node, color );
+				} );
+			}
+		] );
+		this._parameterObservers.set( Parameter.MATERIAL_METALLNESS, [
+			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				const metallness = Parameter.parseNumber( newValue );
+				element.nodes.forEach( node => {
+					assertTransformNode(node, (node: TransformNode) => {
+						if( node instanceof InstancedMesh ) {
+							throw new Error( `Changing parameter "${Parameter.MATERIAL_METALLNESS}" ` +
+								`of an InstancedMesh is not supported. ` +
+								`Tried to change node "${node.id}" on element "${element.id}".` );
+						}
+					});
+					if( !get( node.metadata, 'dirty.material' ) ) {
+						cloneTransformNodeMaterial( node );
+					}
+					if( !get( node.metadata, 'dirty.material.metallness' ) ) {
+						// inject initial value and mark as dirty
+						injectTransformNodeMetadata( node, { dirty: { material: { metallness: oldValue } } } );
+					}
+					setMaterialMetallness( node, metallness );
+				} );
+			}
+		] );
+		this._parameterObservers.set( Parameter.MATERIAL_ROUGHNESS, [
+			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				const roughness = Parameter.parseNumber( newValue );
+				element.nodes.forEach( node => {
+					assertTransformNode(node, (node: TransformNode) => {
+						if( node instanceof InstancedMesh ) {
+							throw new Error( `Changing parameter "${Parameter.MATERIAL_ROUGHNESS}" ` +
+								`of an InstancedMesh is not supported. ` +
+								`Tried to change node "${node.id}" on element "${element.id}".` );
+						}
+					});
+					if( !get( node.metadata, 'dirty.material' ) ) {
+						cloneTransformNodeMaterial( node );
+					}
+					if( !get( node.metadata, 'dirty.material.roughness' ) ) {
+						// inject initial value and mark as dirty
+						injectTransformNodeMetadata( node, { dirty: { material: { roughness: oldValue } } } );
+					}
+					setMaterialRoughness( node, roughness );
+				} );
+			}
+		] );
+		this._parameterObservers.set( Parameter.HIGHLIGHT_COLOR, [
+			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				// trigger Parameter.HIGHLIGHTED observers
+				this._parameterObservers.get( Parameter.HIGHLIGHTED )?.forEach( observer => {
+					observer( element, !!element.highlighted, !!element.highlighted );
+				} );
+			}
+		] );
+		this._parameterObservers.set( Parameter.HIGHLIGHT_ENABLED, [
+			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				let curr;
+				try {
+					curr = Parameter.parseBoolean( newValue );
+				} catch( e ) {
+					return;
+				}
+				switch( curr ) {
+					case true:
+						if( element._highlightLayer ) {
+							break;
+						}
+						element.highlightLayer = new HighlightLayer(
+							DottedPath.create( element.id ).addPart( 'highlight' ).path,
+							element.variant.viewer.scene
+						);
+						break;
+					case false:
+						element.highlightLayer?.dispose();
+						break;
+				}
+			}
+		] );
+		this._parameterObservers.set( Parameter.HIGHLIGHTED, [
+			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				if( !element.inheritedParameters[Parameter.HIGHLIGHT_ENABLED] ) {
+					return;
+				}
+				// trigger Parameter.HIGHLIGHT_ENABLED observers to ensure HighlightLayer
+				this._parameterObservers.get( Parameter.HIGHLIGHT_ENABLED )?.forEach( observer => {
+					observer( element, this.parameters[Parameter.HIGHLIGHT_ENABLED], true );
+				} );
+				let highlighted;
+				try {
+					highlighted = Parameter.parseBoolean( newValue );
+				} catch( e ) {
+					return;
+				}
+				// Add/Remove meshes to previously created highlight layers.
+				if( highlighted === true ) {
+					element.nodes.forEach( node => {
+						assertTransformNode(node, (node: TransformNode) => {
+							if( node instanceof InstancedMesh ) {
+								throw new Error( `Changing parameter "${Parameter.HIGHLIGHTED}" ` +
+									`of an InstancedMesh is not supported. ` +
+									`Tried to change node "${node.id}" on element "${element.id}".` );
+							}
+						});
+						let color = Color3.Green();
+						if( element.inheritedParameters[Parameter.HIGHLIGHT_COLOR] ) {
+							color = Parameter.parseColor( element.inheritedParameters[Parameter.HIGHLIGHT_COLOR] );
+						}
+						if ( typeof element._highlightLayer !== "undefined" ) {
+							addToHighlightLayer( element._highlightLayer, color, node );
+						}
+					} );
+				} else if( highlighted === false ) {
+					element.nodes.forEach( node => {
+						if ( typeof element._highlightLayer !== "undefined" ) {
+							removeFromHighlightLayer( element._highlightLayer, node );
+						}
+					} );
+				}
+			}
+		] );
+		this._parameterObservers.set( Parameter.POSITION, [
+			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				// we have to deal just with root nodes here due to relative impacts in a node tree
+				element.nodes.forEach( node => {
+					// remember absolute position and reset it before translating
+					if( !get( node.metadata, 'position' ) ) {
+						node.metadata.position = node.absolutePosition.clone();
+					}
+					node.setAbsolutePosition( node.metadata.position );
+					// move
+					const distance = Parameter.parseVector( newValue );
+					node.translate( Axis.X, distance.x, Space.WORLD );
+					node.translate( Axis.Y, distance.y, Space.WORLD );
+					node.translate( Axis.Z, distance.z, Space.WORLD );
+				} );
+			}
+		] );
+		this._parameterObservers.set( Parameter.ROTATION, [
+			async ( element: Element, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				// we have to deal just with root nodes here due to relative impacts in a node tree
+				element.nodes.forEach( node => {
+					// remember absolute rotation and reset it before translating
+					if(!get( node.metadata, 'rotation' ) ) {
+						node.metadata.rotation = node.rotation.clone();
+					}
+					node.rotation = node.metadata.rotation;
+					// rotate
+					const rotation = Parameter.parseRotation( newValue );
+					node.rotate( Axis.X, rotation.x, Space.WORLD );
+					node.rotate( Axis.Y, rotation.y, Space.WORLD );
+					node.rotate( Axis.Z, rotation.z, Space.WORLD );
+				} );
+			}
+		] );
+		return this;
+	}
+
+	/**
+	 * Filter for nodes that are not defined or excluded in the `pathDefinitions`.
+	 */
+	protected filterNode( node: TransformNode ): boolean {
+		let includeTokens: string[] = [];
+		this.pathDefinitions.include.forEach( dottedPath => {
+			includeTokens = union( includeTokens, DottedPath.create( dottedPath ).leafTokens );
+		} );
+		const shallKeep = ( dp: DottedPath ) => {
+			const isDirectlyIncluded = !!includeTokens.find( _dp => _dp === dp.path );
+			const isSubOfIncluded = !!this.pathDefinitions.include.find( _dp =>  {
+				return dp.path.startsWith( `${_dp}${DottedPath.DELIMITER}` );
+			} );
+			return isDirectlyIncluded || isSubOfIncluded;
+		};
+		const shallExclude = ( dp: DottedPath ) => {
+			if( !this.pathDefinitions.exclude ) {
+				return false;
+			}
+			return !!this.pathDefinitions.exclude.find( _dp => dp.path === _dp );
+		};
+		return shallKeep( node.metadata.dottedPath ) && !shallExclude( node.metadata.dottedPath );
+	}
+
+	/**
+	 * Asserts whether all {@link pathDefinitions} link to a valid `Node` path.
+	 * @protected
+	 */
+	protected assertPathDefinitions() {
+		const dottedNodes = this.variant.inheritedDottedNodes;
+		if( dottedNodes.size === 0 ) {
+			throw new Error( `There are no mapped nodes for element "${this.id}".` );
+		}
+		const include = this.pathDefinitions.include.map( path => DottedPath.create( path ).path );
+		const exclude = this.pathDefinitions.exclude?.map( path => DottedPath.create( path ).path );
+		const keys = Array.from( dottedNodes.keys() ).map( dottedPath => dottedPath.path );
+		union<string>( include, exclude ).forEach( path => {
+			if( keys.indexOf( path ) === -1 ) {
+				throw new Error( `Node with path "${path}" does not exist for element "${this.id}".` );
+			}
+		} );
+	}
+
+}