@combeenation/3d-viewer 0.0.1-types

package/src/api/classes/element.ts

@@ -0,0 +1,731 @@
+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);
+              if (parameterBag[Parameter.VISIBLE] === false) {
+                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);
+      });
+    });
+  }
+}