@combeenation/3d-viewer 7.1.3 → 8.0.0

package/src/api/classes/element.ts

@@ -1,733 +1,733 @@
-import {
-  activateTransformNode as activate,
-  addToHighlightLayer,
-  addToShadowGenerator,
-  assertMeshCapability,
-  assertTransformNode,
-  cloneTransformNode,
-  cloneTransformNodeMaterial,
-  deactivateTransformNode as deactivate,
-  getClientRectFromMesh,
-  injectNodeMetadata,
-  mapToDottedNodes,
-  removeFromHighlightLayer,
-  removeFromShadowGenerator,
-  setMaterial,
-  setMaterialColor,
-  setMaterialMetallness,
-  setMaterialRoughness,
-  setMaterialTexture,
-  setReceiveShadows,
-  transformTransformNode,
-} from '../util/babylonHelper';
-import { createImageFromImgSrc, createImageFromSvg } from '../util/resourceHelper';
-import { addMissingMaterialObserver } from '../util/sceneLoaderHelper';
-import { VariantParameterizable } from './../classes/variantParameterizable';
-import { DottedPath } from './dottedPath';
-import { Event } from './event';
-import { Parameter } from './parameter';
-import { Variant } from './variant';
-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 { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
-import { Material } from '@babylonjs/core/Materials/material';
-import { Color3 } from '@babylonjs/core/Maths/math.color';
-import { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
-import { Mesh } from '@babylonjs/core/Meshes/mesh';
-import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
-import { has, isArray, isNumber, isPlainObject, merge, union } from 'lodash-es';
-
-/**
- * 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 VariantParameterizable {
-  public readonly nodes: TransformNode[] = [];
-
-  protected readonly _dottedNodes: Map<DottedPath, TransformNode> = new Map();
-
-  protected _highlightLayer?: HighlightLayer;
-
-  /**
-   * Constructor.
-   */
-  protected constructor(public readonly variant: Variant, public readonly name: string) {
-    super(variant, name);
-    if (process.env.NODE_ENV?.toLowerCase().includes('dev')) {
-      this.assertPathDefinitions();
-    }
-    const nodes = this.variant.inheritedNodes.map(node => {
-      const nodeNamingStrategy = {
-        handler: variant.viewer.nodeNamingStrategyHandler,
-        payload: {
-          variantInstance: variant.variantInstance!,
-          variant: variant,
-          variantParameterizable: this,
-        },
-      };
-      return cloneTransformNode(node, nodeNamingStrategy, this.filterNode.bind(this), true);
-    });
-    this.nodes = nodes.filter(node => !!node) as TransformNode[];
-    this._dottedNodes = mapToDottedNodes<TransformNode>(this.nodes, node => node instanceof TransformNode);
-    variant.broadcastEvent(Event.ELEMENT_NODES_CLONED, this);
-    this.addMissingMaterialObservers();
-    this.addParameterObservers();
-  }
-
-  /**
-   * Creates an {@link Element} with given name.
-   */
-  public static async create(variant: Variant, name: string): Promise<Element> {
-    const element = new Element(variant, name);
-    variant.broadcastEvent(Event.ELEMENT_CREATED, element);
-    return element;
-  }
-
-  /**
-   * 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);
-  }
-
-  /**
-   * The actual {@link TransformNode}s that make up this {@link Element}.
-   */
-  get nodesFlat(): TransformNode[] {
-    return this.nodes.reduce(
-      (acc, cur) => [...acc, ...(cur.getChildren(n => n instanceof TransformNode, false) as TransformNode[])],
-      this.nodes
-    );
-  }
-
-  /**
-   * The actual {@link Mesh}es that make up this {@link Element}.
-   * Handy for e.g. creating a bounding box around an entire element.
-   */
-  get meshesFlat(): Mesh[] {
-    return this.nodes.reduce(
-      (acc, cur) => [...acc, ...(cur.getChildren(n => n instanceof Mesh, false) as Mesh[])],
-      this.nodes.filter(n => n instanceof Mesh) as Mesh[]
-    );
-  }
-
-  /**
-   * The actual {@link AbstractMesh}es that make up this {@link Element}.
-   * I.e. (real) Meshes as well as InstancedMeshes.
-   */
-  get abstractMeshesFlat(): AbstractMesh[] {
-    return this.nodes.reduce(
-      (acc, cur) => [...acc, ...(cur.getChildren(n => n instanceof AbstractMesh, false) as AbstractMesh[])],
-      this.nodes.filter(n => n instanceof AbstractMesh) as AbstractMesh[]
-    );
-  }
-
-  /**
-   * The meshes of this {@link Element}.
-   */
-  get meshes(): Mesh[] {
-    return this.nodes.filter(node => node instanceof Mesh) as Mesh[];
-  }
-
-  /**
-   * @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);
-  }
-
-  /**
-   * @see {@link VariantParameterizable.commitParameters}
-   * @emit {@link Event.ELEMENT_PARAMETER_COMMITTED}
-   */
-  public async commitParameters(parameters?: ParameterBag): Promise<VariantParameterizable> {
-    return super.commitParameters(parameters);
-  }
-
-  /**
-   * 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 {
-    // node and material checks and preperation
-    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 && this.variant.viewer.cloneMaterialsOnMutation) {
-      if (node.material && !has(node.metadata, 'dirty.material')) {
-        cloneTransformNodeMaterial(node);
-      }
-      if (!has(node.metadata, 'dirty.material.texture')) {
-        // inject initial value and mark as dirty
-        injectNodeMetadata(node, { dirty: { material: { texture: true } } });
-      }
-    } else if (!node.material) {
-      // paintables should also work if no material is assigned to the node per default
-      // in this case a certain fallback material with fitting default values is defined
-      const pbrMat = new PBRMaterial(`${this.id}.${paintable}.material`, this.variant.viewer.scene);
-      pbrMat.roughness = 1.0;
-      pbrMat.metallic = 1.0;
-      node.material = pbrMat;
-    }
-
-    // TODO: Not sure if this really should be overwritten every time the paintable is redrawn.
-    // Maybe the 3D artist had something in mind when setting a certain transparency mode, which would get overwritten
-    // in this case.
-    // Applying it as a default if no material is set is fine though (see roughness/metallic some lines above).
-    // Removing this line will most likely break existing configurators, so be cautios!
-    node.material.transparencyMode = Material.MATERIAL_ALPHATESTANDBLEND;
-
-    // consider width and height of the paintable
-    const widthAndHeight = {
-      width: imageSource.width,
-      height: imageSource.height,
-    };
-    const paintableDefinition = this.getPaintableDefinition(paintable);
-    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;
-    }
-
-    // create dynamic texture on which the image can be drawn
-    const texture = new DynamicTexture(
-      `${this.id}.${paintable}.texture`,
-      widthAndHeight,
-      this.variant.viewer.scene,
-      false
-    );
-
-    // draw image on texture
-    const ctx = texture.getContext();
-    ctx.drawImage(imageSource, 0, 0);
-    texture.update(false);
-
-    // finally apply the texture on the desired node material
-    setMaterialTexture(node, texture, false);
-
-    return this;
-  }
-
-  /**
-   * Draws a SVG string onto a `paintable` defined via {@link PaintableDefinition}.
-   */
-  public async drawPaintableFromSvg(paintable: string, svgSource: string): Promise<Element> {
-    const image = await createImageFromSvg(svgSource);
-    return this.drawPaintable(paintable, image);
-  }
-
-  /**
-   * Draws an Image from source (URL/URI) onto a `paintable` defined via {@link PaintableDefinition}.
-   */
-  public async drawPaintableFromImgSrc(paintable: string, imgSource: string): Promise<Element> {
-    const image = await createImageFromImgSrc(imgSource);
-    return this.drawPaintable(paintable, image);
-  }
-
-  /**
-   * Adds observers for loading missing materials where needed
-   */
-  protected addMissingMaterialObservers() {
-    for (const abstractMesh of this.abstractMeshesFlat) {
-      addMissingMaterialObserver(abstractMesh);
-    }
-  }
-
-  /**
-   * 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: Undefinable<ParameterValue>, newValue: ParameterValue) => {
-        let visible;
-        try {
-          visible = Parameter.parseBoolean(newValue);
-        } catch (e) {
-          return;
-        }
-        if (visible === true) {
-          // Override visible state and materials if tag manager is in use to support texture lazy loading
-          if (element.variant.viewer.tagManager.parameters.size > 0) {
-            const hiddenNodeNames: string[] = [];
-            element.variant.viewer.tagManager.parameters.forEach((parameterBag, subject) => {
-              const nodes = element.variant.viewer.tagManager.getNodesBySubject(subject);
-              const visibleParamValue = parameterBag[Parameter.VISIBLE];
-              const isVisible = undefined === visibleParamValue || Parameter.parseBoolean(visibleParamValue);
-              if (!isVisible) {
-                hiddenNodeNames.push(...nodes.map(node => node.name));
-              }
-              // overwrite materials immediatly, so that original material of node doesn't get loaded, since it could
-              // be exchanged by the tag manager
-              if (parameterBag[Parameter.MATERIAL]) {
-                nodes.forEach(node => setMaterial(node, parameterBag[Parameter.MATERIAL], false));
-              }
-            });
-            // enable all nodes that are not explicitely hidden by the tag manager
-            element.nodesFlat.map(node => {
-              if (!hiddenNodeNames.includes(node.name)) {
-                node.setEnabled(true);
-              }
-            });
-            return;
-          }
-          // The default behaviour.
-          element.nodes.forEach(node => {
-            injectNodeMetadata(node, { visibility: node.isEnabled() });
-            activate(node);
-          });
-        } else if (visible === false) {
-          element.nodes.forEach(node => {
-            injectNodeMetadata(node, { visibility: node.isEnabled() });
-            deactivate(node);
-          });
-        }
-      },
-    ]);
-    this._parameterObservers.set(Parameter.SCALING, [
-      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
-        // we have to deal just with root nodes here due to relative impacts in a node tree
-        element.nodes.forEach(node =>
-          transformTransformNode(node, {
-            scaling: Parameter.parseVector(newValue),
-            position: Parameter.parseVector(
-              element.inheritedParameters[Parameter.POSITION] || Parameter.getDefaultValue(Parameter.POSITION)
-            ),
-            rotation: Parameter.parseRotation(
-              element.inheritedParameters[Parameter.ROTATION] || Parameter.getDefaultValue(Parameter.ROTATION)
-            ),
-          })
-        );
-      },
-    ]);
-    this._parameterObservers.set(Parameter.POSITION, [
-      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
-        // we have to deal just with root nodes here due to relative impacts in a node tree
-        element.nodes.forEach(node =>
-          transformTransformNode(node, {
-            scaling: Parameter.parseVector(
-              element.inheritedParameters[Parameter.SCALING] || Parameter.getDefaultValue(Parameter.SCALING)
-            ),
-            position: Parameter.parseVector(newValue),
-            rotation: Parameter.parseRotation(
-              element.inheritedParameters[Parameter.ROTATION] || Parameter.getDefaultValue(Parameter.ROTATION)
-            ),
-          })
-        );
-      },
-    ]);
-    this._parameterObservers.set(Parameter.ROTATION, [
-      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
-        // we have to deal just with root nodes here due to relative impacts in a node tree
-        element.nodes.forEach(node =>
-          transformTransformNode(node, {
-            scaling: Parameter.parseVector(
-              element.inheritedParameters[Parameter.SCALING] || Parameter.getDefaultValue(Parameter.SCALING)
-            ),
-            position: Parameter.parseVector(
-              element.inheritedParameters[Parameter.POSITION] || Parameter.getDefaultValue(Parameter.POSITION)
-            ),
-            rotation: Parameter.parseRotation(newValue),
-          })
-        );
-      },
-    ]);
-    this._parameterObservers.set(Parameter.MATERIAL, [
-      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
-        const materialName = newValue.toString();
-        for (const node of element.nodes) {
-          assertTransformNode(node, node => assertMeshCapability(node, Parameter.MATERIAL));
-          setMaterial(node, materialName, true, element.variant);
-        }
-      },
-    ]);
-    this._parameterObservers.set(Parameter.MATERIAL_COLOR, [
-      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
-        const color = Parameter.parseColor(newValue);
-        element.nodes.forEach(node => {
-          assertTransformNode(node, node => assertMeshCapability(node, Parameter.MATERIAL_COLOR));
-          if (this.variant.viewer.cloneMaterialsOnMutation) {
-            if (!has(node.metadata, 'dirty.material')) {
-              cloneTransformNodeMaterial(node);
-            }
-            if (!has(node.metadata, 'dirty.material.color')) {
-              // inject initial value and mark as dirty
-              injectNodeMetadata(node, { dirty: { material: { color: oldValue } } });
-            }
-          }
-          setMaterialColor(node, color);
-        });
-      },
-    ]);
-    this._parameterObservers.set(Parameter.MATERIAL_METALLNESS, [
-      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
-        const metallness = Parameter.parseNumber(newValue);
-        element.nodes.forEach(node => {
-          assertTransformNode(node, node => assertMeshCapability(node, Parameter.MATERIAL_METALLNESS));
-          if (this.variant.viewer.cloneMaterialsOnMutation) {
-            if (!has(node.metadata, 'dirty.material')) {
-              cloneTransformNodeMaterial(node);
-            }
-            if (!has(node.metadata, 'dirty.material.metallness')) {
-              // inject initial value and mark as dirty
-              injectNodeMetadata(node, { dirty: { material: { metallness: oldValue } } });
-            }
-          }
-          setMaterialMetallness(node, metallness);
-        });
-      },
-    ]);
-    this._parameterObservers.set(Parameter.MATERIAL_ROUGHNESS, [
-      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
-        const roughness = Parameter.parseNumber(newValue);
-        element.nodes.forEach(node => {
-          assertTransformNode(node, node => assertMeshCapability(node, Parameter.MATERIAL_ROUGHNESS));
-          if (this.variant.viewer.cloneMaterialsOnMutation) {
-            if (!has(node.metadata, 'dirty.material')) {
-              cloneTransformNodeMaterial(node);
-            }
-            if (!has(node.metadata, 'dirty.material.roughness')) {
-              // inject initial value and mark as dirty
-              injectNodeMetadata(node, { dirty: { material: { roughness: oldValue } } });
-            }
-          }
-          setMaterialRoughness(node, roughness);
-        });
-      },
-    ]);
-    this._parameterObservers.set(Parameter.HIGHLIGHT_COLOR, [
-      async (element: Element, oldValue: Undefinable<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: Undefinable<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: Undefinable<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 => assertMeshCapability(node, Parameter.HIGHLIGHTED));
-            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.CAST_SHADOW, [
-      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
-        let castShadow;
-        try {
-          castShadow = Parameter.parseBoolean(newValue);
-        } catch (e) {
-          return;
-        }
-        let lightCsl = element.inheritedParameters[Parameter.CAST_SHADOW_FROM_LIGHTS];
-        if (!lightCsl) {
-          lightCsl = element.variant.inheritedViewerLights.map(l => l.name).join(',');
-        }
-        if (castShadow === true) {
-          await this.castShadowValueHandler(lightCsl, addToShadowGenerator);
-        }
-        if (castShadow === false) {
-          await this.castShadowValueHandler(lightCsl, removeFromShadowGenerator);
-        }
-      },
-    ]);
-    this._parameterObservers.set(Parameter.CAST_SHADOW_FROM_LIGHTS, [
-      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
-        // TODO: Possible performance issue in combination with CAST_SHADOW, since both observers are initially called
-        //       when CAST_SHADOW and CAST_SHADOW_FROM_LIGHTS are defined in the spec.
-        const lightCsl = element.variant.inheritedViewerLights.map(l => l.name).join(',');
-        // cleanup all shadow generators
-        await this.castShadowValueHandler(lightCsl, removeFromShadowGenerator);
-        if (element.castShadow === true) {
-          // if newValue is undefined or '' then set newValue to lightCsl (use all lights)
-          if (!newValue) {
-            newValue = lightCsl;
-          }
-          await this.castShadowValueHandler(newValue, addToShadowGenerator);
-        }
-      },
-    ]);
-    this._parameterObservers.set(Parameter.RECEIVE_SHADOWS, [
-      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
-        element.nodes.forEach(node => setReceiveShadows(node, Parameter.parseBoolean(newValue)));
-      },
-    ]);
-    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}".`);
-      }
-    });
-  }
-
-  /**
-   * Handles callback for given light parameter.
-   */
-  private async castShadowValueHandler(lightCsl: ParameterValue, mutator: CallableFunction) {
-    const lights: Light[] = [];
-    for (const lightName of Parameter.parseCommaSeparatedList(lightCsl)) {
-      const viewerLight = await this.variant.getViewerLight(lightName);
-      if (viewerLight) {
-        lights.push(viewerLight.light);
-      }
-    }
-    const shadowGenerators = lights.map(light => light?.getShadowGenerator() as ShadowGenerator).filter(Boolean);
-    shadowGenerators.forEach(generator => {
-      this.nodes.forEach(node => {
-        mutator(generator, node);
-      });
-    });
-  }
-}
+import {
+  activateTransformNode as activate,
+  addToHighlightLayer,
+  addToShadowGenerator,
+  assertMeshCapability,
+  assertTransformNode,
+  cloneTransformNode,
+  cloneTransformNodeMaterial,
+  deactivateTransformNode as deactivate,
+  getClientRectFromMesh,
+  injectNodeMetadata,
+  mapToDottedNodes,
+  removeFromHighlightLayer,
+  removeFromShadowGenerator,
+  setMaterial,
+  setMaterialColor,
+  setMaterialMetallness,
+  setMaterialRoughness,
+  setMaterialTexture,
+  setReceiveShadows,
+  transformTransformNode,
+} from '../util/babylonHelper';
+import { createImageFromImgSrc, createImageFromSvg } from '../util/resourceHelper';
+import { addMissingMaterialObserver } from '../util/sceneLoaderHelper';
+import { VariantParameterizable } from './../classes/variantParameterizable';
+import { DottedPath } from './dottedPath';
+import { Event } from './event';
+import { Parameter } from './parameter';
+import { Variant } from './variant';
+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 { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
+import { Material } from '@babylonjs/core/Materials/material';
+import { Color3 } from '@babylonjs/core/Maths/math.color';
+import { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
+import { Mesh } from '@babylonjs/core/Meshes/mesh';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { has, isArray, isNumber, isPlainObject, merge, union } from 'lodash-es';
+
+/**
+ * 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 VariantParameterizable {
+  public readonly nodes: TransformNode[] = [];
+
+  protected readonly _dottedNodes: Map<DottedPath, TransformNode> = new Map();
+
+  protected _highlightLayer?: HighlightLayer;
+
+  /**
+   * Constructor.
+   */
+  protected constructor(public readonly variant: Variant, public readonly name: string) {
+    super(variant, name);
+    if (process.env.NODE_ENV?.toLowerCase().includes('dev')) {
+      this.assertPathDefinitions();
+    }
+    const nodes = this.variant.inheritedNodes.map(node => {
+      const nodeNamingStrategy = {
+        handler: variant.viewer.nodeNamingStrategyHandler,
+        payload: {
+          variantInstance: variant.variantInstance!,
+          variant: variant,
+          variantParameterizable: this,
+        },
+      };
+      return cloneTransformNode(node, nodeNamingStrategy, this.filterNode.bind(this), true);
+    });
+    this.nodes = nodes.filter(node => !!node) as TransformNode[];
+    this._dottedNodes = mapToDottedNodes<TransformNode>(this.nodes, node => node instanceof TransformNode);
+    variant.broadcastEvent(Event.ELEMENT_NODES_CLONED, this);
+    this.addMissingMaterialObservers();
+    this.addParameterObservers();
+  }
+
+  /**
+   * Creates an {@link Element} with given name.
+   */
+  public static async create(variant: Variant, name: string): Promise<Element> {
+    const element = new Element(variant, name);
+    variant.broadcastEvent(Event.ELEMENT_CREATED, element);
+    return element;
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * The actual {@link TransformNode}s that make up this {@link Element}.
+   */
+  get nodesFlat(): TransformNode[] {
+    return this.nodes.reduce(
+      (acc, cur) => [...acc, ...(cur.getChildren(n => n instanceof TransformNode, false) as TransformNode[])],
+      this.nodes
+    );
+  }
+
+  /**
+   * The actual {@link Mesh}es that make up this {@link Element}.
+   * Handy for e.g. creating a bounding box around an entire element.
+   */
+  get meshesFlat(): Mesh[] {
+    return this.nodes.reduce(
+      (acc, cur) => [...acc, ...(cur.getChildren(n => n instanceof Mesh, false) as Mesh[])],
+      this.nodes.filter(n => n instanceof Mesh) as Mesh[]
+    );
+  }
+
+  /**
+   * The actual {@link AbstractMesh}es that make up this {@link Element}.
+   * I.e. (real) Meshes as well as InstancedMeshes.
+   */
+  get abstractMeshesFlat(): AbstractMesh[] {
+    return this.nodes.reduce(
+      (acc, cur) => [...acc, ...(cur.getChildren(n => n instanceof AbstractMesh, false) as AbstractMesh[])],
+      this.nodes.filter(n => n instanceof AbstractMesh) as AbstractMesh[]
+    );
+  }
+
+  /**
+   * The meshes of this {@link Element}.
+   */
+  get meshes(): Mesh[] {
+    return this.nodes.filter(node => node instanceof Mesh) as Mesh[];
+  }
+
+  /**
+   * @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);
+  }
+
+  /**
+   * @see {@link VariantParameterizable.commitParameters}
+   * @emit {@link Event.ELEMENT_PARAMETER_COMMITTED}
+   */
+  public async commitParameters(parameters?: ParameterBag): Promise<VariantParameterizable> {
+    return super.commitParameters(parameters);
+  }
+
+  /**
+   * 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 {
+    // node and material checks and preperation
+    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 && this.variant.viewer.cloneMaterialsOnMutation) {
+      if (node.material && !has(node.metadata, 'dirty.material')) {
+        cloneTransformNodeMaterial(node);
+      }
+      if (!has(node.metadata, 'dirty.material.texture')) {
+        // inject initial value and mark as dirty
+        injectNodeMetadata(node, { dirty: { material: { texture: true } } });
+      }
+    } else if (!node.material) {
+      // paintables should also work if no material is assigned to the node per default
+      // in this case a certain fallback material with fitting default values is defined
+      const pbrMat = new PBRMaterial(`${this.id}.${paintable}.material`, this.variant.viewer.scene);
+      pbrMat.roughness = 1.0;
+      pbrMat.metallic = 1.0;
+      node.material = pbrMat;
+    }
+
+    // TODO: Not sure if this really should be overwritten every time the paintable is redrawn.
+    // Maybe the 3D artist had something in mind when setting a certain transparency mode, which would get overwritten
+    // in this case.
+    // Applying it as a default if no material is set is fine though (see roughness/metallic some lines above).
+    // Removing this line will most likely break existing configurators, so be cautios!
+    node.material.transparencyMode = Material.MATERIAL_ALPHATESTANDBLEND;
+
+    // consider width and height of the paintable
+    const widthAndHeight = {
+      width: imageSource.width,
+      height: imageSource.height,
+    };
+    const paintableDefinition = this.getPaintableDefinition(paintable);
+    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;
+    }
+
+    // create dynamic texture on which the image can be drawn
+    const texture = new DynamicTexture(
+      `${this.id}.${paintable}.texture`,
+      widthAndHeight,
+      this.variant.viewer.scene,
+      false
+    );
+
+    // draw image on texture
+    const ctx = texture.getContext();
+    ctx.drawImage(imageSource, 0, 0);
+    texture.update(false);
+
+    // finally apply the texture on the desired node material
+    setMaterialTexture(node, texture, false);
+
+    return this;
+  }
+
+  /**
+   * Draws a SVG string onto a `paintable` defined via {@link PaintableDefinition}.
+   */
+  public async drawPaintableFromSvg(paintable: string, svgSource: string): Promise<Element> {
+    const image = await createImageFromSvg(svgSource);
+    return this.drawPaintable(paintable, image);
+  }
+
+  /**
+   * Draws an Image from source (URL/URI) onto a `paintable` defined via {@link PaintableDefinition}.
+   */
+  public async drawPaintableFromImgSrc(paintable: string, imgSource: string): Promise<Element> {
+    const image = await createImageFromImgSrc(imgSource);
+    return this.drawPaintable(paintable, image);
+  }
+
+  /**
+   * Adds observers for loading missing materials where needed
+   */
+  protected addMissingMaterialObservers() {
+    for (const abstractMesh of this.abstractMeshesFlat) {
+      addMissingMaterialObserver(abstractMesh);
+    }
+  }
+
+  /**
+   * 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: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        let visible;
+        try {
+          visible = Parameter.parseBoolean(newValue);
+        } catch (e) {
+          return;
+        }
+        if (visible === true) {
+          // Override visible state and materials if tag manager is in use to support texture lazy loading
+          if (element.variant.viewer.tagManager.parameters.size > 0) {
+            const hiddenNodeNames: string[] = [];
+            element.variant.viewer.tagManager.parameters.forEach((parameterBag, subject) => {
+              const nodes = element.variant.viewer.tagManager.getNodesBySubject(subject);
+              const visibleParamValue = parameterBag[Parameter.VISIBLE];
+              const isVisible = undefined === visibleParamValue || Parameter.parseBoolean(visibleParamValue);
+              if (!isVisible) {
+                hiddenNodeNames.push(...nodes.map(node => node.name));
+              }
+              // overwrite materials immediatly, so that original material of node doesn't get loaded, since it could
+              // be exchanged by the tag manager
+              if (parameterBag[Parameter.MATERIAL]) {
+                nodes.forEach(node => setMaterial(node, parameterBag[Parameter.MATERIAL], false));
+              }
+            });
+            // enable all nodes that are not explicitely hidden by the tag manager
+            element.nodesFlat.map(node => {
+              if (!hiddenNodeNames.includes(node.name)) {
+                node.setEnabled(true);
+              }
+            });
+            return;
+          }
+          // The default behaviour.
+          element.nodes.forEach(node => {
+            injectNodeMetadata(node, { visibility: node.isEnabled() });
+            activate(node);
+          });
+        } else if (visible === false) {
+          element.nodes.forEach(node => {
+            injectNodeMetadata(node, { visibility: node.isEnabled() });
+            deactivate(node);
+          });
+        }
+      },
+    ]);
+    this._parameterObservers.set(Parameter.SCALING, [
+      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        // we have to deal just with root nodes here due to relative impacts in a node tree
+        element.nodes.forEach(node =>
+          transformTransformNode(node, {
+            scaling: Parameter.parseVector(newValue),
+            position: Parameter.parseVector(
+              element.inheritedParameters[Parameter.POSITION] || Parameter.getDefaultValue(Parameter.POSITION)
+            ),
+            rotation: Parameter.parseRotation(
+              element.inheritedParameters[Parameter.ROTATION] || Parameter.getDefaultValue(Parameter.ROTATION)
+            ),
+          })
+        );
+      },
+    ]);
+    this._parameterObservers.set(Parameter.POSITION, [
+      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        // we have to deal just with root nodes here due to relative impacts in a node tree
+        element.nodes.forEach(node =>
+          transformTransformNode(node, {
+            scaling: Parameter.parseVector(
+              element.inheritedParameters[Parameter.SCALING] || Parameter.getDefaultValue(Parameter.SCALING)
+            ),
+            position: Parameter.parseVector(newValue),
+            rotation: Parameter.parseRotation(
+              element.inheritedParameters[Parameter.ROTATION] || Parameter.getDefaultValue(Parameter.ROTATION)
+            ),
+          })
+        );
+      },
+    ]);
+    this._parameterObservers.set(Parameter.ROTATION, [
+      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        // we have to deal just with root nodes here due to relative impacts in a node tree
+        element.nodes.forEach(node =>
+          transformTransformNode(node, {
+            scaling: Parameter.parseVector(
+              element.inheritedParameters[Parameter.SCALING] || Parameter.getDefaultValue(Parameter.SCALING)
+            ),
+            position: Parameter.parseVector(
+              element.inheritedParameters[Parameter.POSITION] || Parameter.getDefaultValue(Parameter.POSITION)
+            ),
+            rotation: Parameter.parseRotation(newValue),
+          })
+        );
+      },
+    ]);
+    this._parameterObservers.set(Parameter.MATERIAL, [
+      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        const materialName = newValue.toString();
+        for (const node of element.nodes) {
+          assertTransformNode(node, node => assertMeshCapability(node, Parameter.MATERIAL));
+          setMaterial(node, materialName, true, element.variant);
+        }
+      },
+    ]);
+    this._parameterObservers.set(Parameter.MATERIAL_COLOR, [
+      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        const color = Parameter.parseColor(newValue);
+        element.nodes.forEach(node => {
+          assertTransformNode(node, node => assertMeshCapability(node, Parameter.MATERIAL_COLOR));
+          if (this.variant.viewer.cloneMaterialsOnMutation) {
+            if (!has(node.metadata, 'dirty.material')) {
+              cloneTransformNodeMaterial(node);
+            }
+            if (!has(node.metadata, 'dirty.material.color')) {
+              // inject initial value and mark as dirty
+              injectNodeMetadata(node, { dirty: { material: { color: oldValue } } });
+            }
+          }
+          setMaterialColor(node, color);
+        });
+      },
+    ]);
+    this._parameterObservers.set(Parameter.MATERIAL_METALLNESS, [
+      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        const metallness = Parameter.parseNumber(newValue);
+        element.nodes.forEach(node => {
+          assertTransformNode(node, node => assertMeshCapability(node, Parameter.MATERIAL_METALLNESS));
+          if (this.variant.viewer.cloneMaterialsOnMutation) {
+            if (!has(node.metadata, 'dirty.material')) {
+              cloneTransformNodeMaterial(node);
+            }
+            if (!has(node.metadata, 'dirty.material.metallness')) {
+              // inject initial value and mark as dirty
+              injectNodeMetadata(node, { dirty: { material: { metallness: oldValue } } });
+            }
+          }
+          setMaterialMetallness(node, metallness);
+        });
+      },
+    ]);
+    this._parameterObservers.set(Parameter.MATERIAL_ROUGHNESS, [
+      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        const roughness = Parameter.parseNumber(newValue);
+        element.nodes.forEach(node => {
+          assertTransformNode(node, node => assertMeshCapability(node, Parameter.MATERIAL_ROUGHNESS));
+          if (this.variant.viewer.cloneMaterialsOnMutation) {
+            if (!has(node.metadata, 'dirty.material')) {
+              cloneTransformNodeMaterial(node);
+            }
+            if (!has(node.metadata, 'dirty.material.roughness')) {
+              // inject initial value and mark as dirty
+              injectNodeMetadata(node, { dirty: { material: { roughness: oldValue } } });
+            }
+          }
+          setMaterialRoughness(node, roughness);
+        });
+      },
+    ]);
+    this._parameterObservers.set(Parameter.HIGHLIGHT_COLOR, [
+      async (element: Element, oldValue: Undefinable<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: Undefinable<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: Undefinable<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 => assertMeshCapability(node, Parameter.HIGHLIGHTED));
+            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.CAST_SHADOW, [
+      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        let castShadow;
+        try {
+          castShadow = Parameter.parseBoolean(newValue);
+        } catch (e) {
+          return;
+        }
+        let lightCsl = element.inheritedParameters[Parameter.CAST_SHADOW_FROM_LIGHTS];
+        if (!lightCsl) {
+          lightCsl = element.variant.inheritedViewerLights.map(l => l.name).join(',');
+        }
+        if (castShadow === true) {
+          await this.castShadowValueHandler(lightCsl, addToShadowGenerator);
+        }
+        if (castShadow === false) {
+          await this.castShadowValueHandler(lightCsl, removeFromShadowGenerator);
+        }
+      },
+    ]);
+    this._parameterObservers.set(Parameter.CAST_SHADOW_FROM_LIGHTS, [
+      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        // TODO: Possible performance issue in combination with CAST_SHADOW, since both observers are initially called
+        //       when CAST_SHADOW and CAST_SHADOW_FROM_LIGHTS are defined in the spec.
+        const lightCsl = element.variant.inheritedViewerLights.map(l => l.name).join(',');
+        // cleanup all shadow generators
+        await this.castShadowValueHandler(lightCsl, removeFromShadowGenerator);
+        if (element.castShadow === true) {
+          // if newValue is undefined or '' then set newValue to lightCsl (use all lights)
+          if (!newValue) {
+            newValue = lightCsl;
+          }
+          await this.castShadowValueHandler(newValue, addToShadowGenerator);
+        }
+      },
+    ]);
+    this._parameterObservers.set(Parameter.RECEIVE_SHADOWS, [
+      async (element: Element, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        element.nodes.forEach(node => setReceiveShadows(node, Parameter.parseBoolean(newValue)));
+      },
+    ]);
+    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}".`);
+      }
+    });
+  }
+
+  /**
+   * Handles callback for given light parameter.
+   */
+  private async castShadowValueHandler(lightCsl: ParameterValue, mutator: CallableFunction) {
+    const lights: Light[] = [];
+    for (const lightName of Parameter.parseCommaSeparatedList(lightCsl)) {
+      const viewerLight = await this.variant.getViewerLight(lightName);
+      if (viewerLight) {
+        lights.push(viewerLight.light);
+      }
+    }
+    const shadowGenerators = lights.map(light => light?.getShadowGenerator() as ShadowGenerator).filter(Boolean);
+    shadowGenerators.forEach(generator => {
+      this.nodes.forEach(node => {
+        mutator(generator, node);
+      });
+    });
+  }
+}