@combeenation/3d-viewer 12.4.1 → 12.4.3

package/src/api/manager/tagManager.ts

@@ -1,572 +1,572 @@
-import { Event, emitter } from '../classes/event';
-import { FuzzyMap } from '../classes/fuzzyMap';
-import { Parameter } from '../classes/parameter';
-import { Viewer } from '../classes/viewer';
-import { ViewerError, ViewerErrorIds } from '../classes/viewerError';
-import {
-  assertMeshCapability,
-  drawPaintableOnMaterial,
-  injectMetadata,
-  mapTags,
-  setMaterial,
-} from '../util/babylonHelper';
-import { createImageFromImgSrc, createImageFromSvg } from '../util/resourceHelper';
-import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
-import { Tags } from '@babylonjs/core/Misc/tags';
-import isSvg from 'is-svg';
-import { clone, get, merge, uniq } from 'lodash-es';
-
-export class TagManager {
-  public readonly parameters: TagManagerParameterBag = new FuzzyMap();
-
-  public readonly parameterObservers: TagManagerParameterObserverBag = new Map();
-
-  /**
-   * Constructor.
-   */
-  public constructor(protected viewer: Viewer) {
-    this.addParameterObservers();
-  }
-
-  /**
-   * Calls the {@link ParameterObserver} for given {@link Parameter} and applies the {@link ParameterValue} on all
-   * nodes with given tagName.
-   */
-  public async setTagParameterValue(
-    tagName: string,
-    parameterName: string,
-    value: ParameterValue
-  ): Promise<TagManagerParameterObserverResultBag> {
-    return await this.handleParameter({ tagName: tagName }, parameterName, value);
-  }
-
-  /**
-   * Calls the {@link ParameterObserver} for given {@link Parameter} and applies the {@link ParameterValue} on all
-   * nodes with given nodeName.
-   */
-  public async setNodeParameterValue(
-    nodeName: string,
-    parameterName: string,
-    value: ParameterValue
-  ): Promise<TagManagerParameterObserverResultBag> {
-    return await this.handleParameter({ nodeName: nodeName }, parameterName, value);
-  }
-
-  /**
-   * Calls the {@link ParameterObserver} for given {@link Parameter} and applies the {@link ParameterValue} on all
-   * materials with given materialName.
-   */
-  public async setMaterialParameterValue(
-    materialName: string,
-    parameterName: string,
-    value: ParameterValue
-  ): Promise<TagManagerParameterObserverResultBag> {
-    return await this.handleParameter({ materialName: materialName }, parameterName, value);
-  }
-
-  /**
-   * Splits the passed {@link TagManagerParameterValue}s into individual values and calls all {@link ParameterObserver}s
-   * of all {@link Parameter}s with the respective {@link TagManagerSubject} and {@link ParameterValue}. The result is a
-   * map of passed {@link TagManagerParameterValue}s and the associated {@link TagManagerParameterObserverResult} of the
-   * {@link ParameterObserver}.
-   */
-  public async setParameterValues(
-    values: TagManagerParameterValue[]
-  ): Promise<Map<TagManagerParameterValue, TagManagerParameterObserverResultBag>> {
-    const observerResultMap: Map<TagManagerParameterValue, TagManagerParameterObserverResultBag> = new Map();
-    const tagPromises: Promise<TagManagerParameterObserverResultBag>[] = [];
-    const nodePromises: Promise<TagManagerParameterObserverResultBag>[] = [];
-    const materialPromises: Promise<TagManagerParameterObserverResultBag>[] = [];
-    for (const value of values) {
-      const subject: TagManagerSubject = {};
-      if (value.tagName) {
-        subject.tagName = value.tagName;
-      }
-      if (value.nodeName) {
-        subject.nodeName = value.nodeName;
-      }
-      if (value.materialName) {
-        subject.materialName = value.materialName;
-      }
-      const observerResultPromise = this.handleParameter(subject, value.parameterName, value.value);
-      observerResultPromise.then(result => observerResultMap.set(value, result));
-      if (value.tagName) {
-        tagPromises.push(observerResultPromise);
-      }
-      if (value.nodeName) {
-        nodePromises.push(observerResultPromise);
-      }
-      if (value.materialName) {
-        materialPromises.push(observerResultPromise);
-      }
-    }
-    await Promise.all(tagPromises);
-    await Promise.all(nodePromises);
-    await Promise.all(materialPromises);
-    return observerResultMap;
-  }
-
-  /**
-   * Gets a list of {@link TagManagerSubject}s that are present in both the state of the {@link TagManager}'s
-   * {@link parameters} and the given object.
-   */
-  public getSubjectsFor(object: TransformNode | Material): TagManagerSubject[] {
-    return [...this.parameters.keys()].filter(
-      subject =>
-        (subject.tagName && Tags.MatchesQuery(object, subject.tagName)) ||
-        (subject.nodeName && object.name === subject.nodeName) ||
-        (subject.materialName && object.name === subject.materialName)
-    );
-  }
-
-  /**
-   * Gets a list of {@link TagManagerSubject}s that are present in both the state of the {@link TagManager}'s
-   * {@link parameters} and the given objects.
-   */
-  public getApplicableSubjectsFor(objects: (TransformNode | Material)[]): TagManagerSubject[] {
-    let applicableSubjects: TagManagerSubject[] = [];
-    for (const object of objects) {
-      const subjects = this.getSubjectsFor(object);
-      applicableSubjects = [...applicableSubjects, ...subjects];
-    }
-    return uniq(applicableSubjects);
-  }
-
-  /**
-   * Applies all existing states of the {@link TagManager}'s {@link parameters} for given {@link TagManagerSubject}s.
-   */
-  public async applyExistingParameterValuesFor(
-    subjects: TagManagerSubject[]
-  ): Promise<Map<TagManagerSubject, TagManagerParameterObserverResultBag>> {
-    const observerResultMap: Map<TagManagerSubject, TagManagerParameterObserverResultBag> = new Map();
-    let tagPromises: Promise<TagManagerParameterObserverResultBag>[] = [];
-    let nodePromises: Promise<TagManagerParameterObserverResultBag>[] = [];
-    let materialPromises: Promise<TagManagerParameterObserverResultBag>[] = [];
-    for (const subject of subjects) {
-      const observerResultPromises = this.handleParameterBag(subject, this.parameters.get(subject)!);
-      for (const observerResultPromise of observerResultPromises) {
-        observerResultPromise.then(result => observerResultMap.set(subject, result));
-      }
-      if (subject.tagName) {
-        tagPromises = [...tagPromises, ...observerResultPromises];
-      }
-      if (subject.nodeName) {
-        nodePromises = [...nodePromises, ...observerResultPromises];
-      }
-      if (subject.materialName) {
-        materialPromises = [...materialPromises, ...observerResultPromises];
-      }
-    }
-    await Promise.all(tagPromises);
-    await Promise.all(nodePromises);
-    await Promise.all(materialPromises);
-    return observerResultMap;
-  }
-
-  /**
-   * Does the same as {@link setParameterValues} with the difference that all existing states of the
-   * {@link TagManager}'s {@link parameters} are applied to all given nodes.
-   */
-  public async applyExistingParameterValuesTo(
-    objects: (TransformNode | Material)[]
-  ): Promise<Map<TagManagerSubject, TagManagerParameterObserverResultBag>> {
-    return this.applyExistingParameterValuesFor(this.getApplicableSubjectsFor(objects));
-  }
-
-  /**
-   * Applies all existing states of the {@link TagManager}'s {@link parameters} for all {@link TagManagerSubject}s.
-   */
-  public async applyExistingParameterValues(): Promise<Map<TagManagerSubject, TagManagerParameterObserverResultBag>> {
-    return this.applyExistingParameterValuesFor([...this.parameters.keys()]);
-  }
-
-  /**
-   * Maps all tags on given nodes with the {@link TagMapping} and updates the state of the {@link TagManager}'s
-   * {@link parameters} for all new tags.
-   * Also updates the state of all nodes in the tag managers parameter state.
-   */
-  public mapNodesAndTags(nodes: TransformNode[], tagMapping: TagMapping): TagManager {
-    this.updateParametersWithNodeAndTagMapping(nodes, tagMapping);
-    mapTags(nodes, tagMapping);
-    return this;
-  }
-
-  /**
-   * Gets a distinct list of all tags within the current scene.
-   */
-  public getAllTags(): string[] {
-    const tags: string[] = [];
-    const nodes = this.viewer.scene.getNodes();
-    for (const node of nodes) {
-      tags.push(...Object.keys(Tags.GetTags(node, false) ?? {}));
-    }
-    return [...new Set(tags)];
-  }
-
-  /**
-   * Prints the state of the {@link TagManager}'s {@link parameters} to the console.
-   */
-  public printAllTags(): void {
-    const printable = [];
-    for (const subject of this.parameters.keys()) {
-      const parameterBag = this.parameters.get(subject);
-      for (const parameter in parameterBag) {
-        printable.push({
-          subject: JSON.stringify(subject),
-          parameter: parameter,
-          value: parameterBag[parameter],
-          nodes: this.getNodesBySubject(subject),
-        });
-      }
-    }
-    console.table(printable);
-  }
-
-  /**
-   * Prints the state of the {@link TagManager}'s {@link parameters} for one tagName to the console.
-   */
-  public printTagInfo(tagName: string): void {
-    const parameterBag = this.parameters.get({ tagName: tagName });
-    const printable = [];
-    for (const parameter in parameterBag) {
-      printable.push({
-        parameter: parameter,
-        value: parameterBag[parameter],
-        nodes: this.getNodesBySubject({ tagName: tagName }),
-      });
-    }
-    console.table(printable);
-  }
-
-  /**
-   * Sets a {@link ParameterObserver} for the given {@link Parameter}.
-   *
-   * The observer should return `false` in cases where the given value was not actually applied. E.g. when wanting to
-   * apply a property on the given `node`s material which doesn't exist at the time the observer is called etc.
-   */
-  public setParameterObserver(parameter: string, observer: TagManagerParameterObserver): TagManager {
-    this.parameterObservers.set(parameter, observer);
-    return this;
-  }
-
-  /**
-   * Gets all nodes for given {@link TagManagerSubject} on the Babylon.js scene.
-   */
-  public getNodesBySubject(subject: TagManagerSubject, predicate?: (node: TransformNode) => boolean): TransformNode[] {
-    let nodes: TransformNode[] = [];
-    if (subject.tagName) {
-      nodes = [
-        ...nodes,
-        ...this.viewer.scene.getTransformNodesByTags(subject.tagName, predicate),
-        ...this.viewer.scene.getMeshesByTags(subject.tagName, predicate),
-      ];
-    }
-    if (subject.nodeName) {
-      nodes = [
-        ...nodes,
-        this.viewer.scene.getTransformNodeByName(subject.nodeName),
-        this.viewer.scene.getMeshByName(subject.nodeName),
-      ].filter(t => !!t && (!predicate || predicate(t))) as TransformNode[];
-    }
-    return nodes;
-  }
-
-  /**
-   * Gets all materials for given {@link TagManagerSubject} on the Babylon.js scene.
-   */
-  public getMaterialsBySubject(subject: TagManagerSubject, predicate?: (material: Material) => boolean): Material[] {
-    let materials: Material[] = [];
-    if (subject.tagName) {
-      materials = [...materials, ...this.viewer.scene.getMaterialByTags(subject.tagName, predicate)];
-    }
-    if (subject.materialName) {
-      materials = [...materials, this.viewer.scene.getMaterialByName(subject.materialName)].filter(
-        t => !!t && (!predicate || predicate(t))
-      ) as Material[];
-    }
-    return materials;
-  }
-
-  /**
-   * Registers observers that are called on every new object added to the Babylon.js scene.
-   * The observers ensure that each new object gets the state of the {@link TagManager}'s {@link parameters} applied.
-   */
-  public registerNewObjectObservers(scene: Scene) {
-    // nodes and meshes
-    const onNewTransformNodeAdded = (node: TransformNode) => {
-      /* NOTE:
-         Removed the check for created instances here since it is not guaranteed that all instances
-         created means that there is no scenario where new nodes should get TagManager parameters applied.
-         Instead, we check for the state to be enabled via the `onEnabledStateChangedObservable` below.
-       */
-      const onEnabledStateChangedObserver = node.onEnabledStateChangedObservable.add(async state => {
-        if (!state) {
-          // if the node is disabled, means ignoring also "ghost nodes"
-          return;
-        }
-        await this.applyExistingParameterValuesTo([node]);
-        node.onEnabledStateChangedObservable.remove(onEnabledStateChangedObserver);
-      });
-      node.onEnabledStateChangedObservable.makeObserverBottomPriority(onEnabledStateChangedObserver!);
-    };
-    scene.onNewTransformNodeAddedObservable.makeObserverBottomPriority(
-      scene.onNewTransformNodeAddedObservable.add(onNewTransformNodeAdded)!
-    );
-    scene.onNewMeshAddedObservable.makeObserverBottomPriority(
-      scene.onNewMeshAddedObservable.add(onNewTransformNodeAdded)!
-    );
-    // materials
-    const onNewMaterialAdded = (material: Material) => {
-      /* NOTE:
-				 We have to wait until a material is bound to a Mesh. In all other scenarios, the material
-				 is not "fully ready" or even empty (without working attributes/properties).
-			 */
-      const onMaterialBindObserver = material.onBindObservable.add(async abstractMesh => {
-        await this.applyExistingParameterValuesTo([material]);
-        material.onBindObservable.remove(onMaterialBindObserver);
-      });
-      material.onBindObservable.makeObserverBottomPriority(onMaterialBindObserver!);
-    };
-    scene.onNewMaterialAddedObservable.makeObserverBottomPriority(
-      scene.onNewMaterialAddedObservable.add(onNewMaterialAdded)!
-    );
-  }
-
-  /**
-   * Adds the default {@link ParameterObserver}s.
-   * @protected
-   */
-  protected addParameterObservers(): TagManager {
-    this.parameterObservers.set(Parameter.VISIBLE, async payload => {
-      const visible = Parameter.parseBoolean(payload.newValue);
-      if (visible === true) {
-        for (const node of payload.nodes) {
-          node.setEnabled(true);
-        }
-      } else if (visible === false) {
-        for (const node of payload.nodes) {
-          node.setEnabled(false);
-        }
-      }
-      return true;
-    });
-    this.parameterObservers.set(Parameter.SCALING, async payload => {
-      for (const node of payload.nodes) {
-        node.scaling = Parameter.parseVector(payload.newValue);
-      }
-      return true;
-    });
-    this.parameterObservers.set(Parameter.POSITION, async payload => {
-      for (const node of payload.nodes) {
-        node.position = Parameter.parseVector(payload.newValue);
-      }
-      return true;
-    });
-    this.parameterObservers.set(Parameter.ROTATION, async payload => {
-      for (const node of payload.nodes) {
-        node.rotation = Parameter.parseRotation(payload.newValue);
-      }
-      return true;
-    });
-    this.parameterObservers.set(Parameter.MATERIAL, async payload => {
-      for (const node of payload.nodes) {
-        assertMeshCapability(node, Parameter.MATERIAL);
-        setMaterial(node, payload.newValue.toString(), false);
-      }
-      return true;
-    });
-    this.parameterObservers.set(Parameter.COLOR, async payload => {
-      const color = Parameter.parseColor(payload.newValue);
-      for (const material of payload.materials) {
-        const materialCls = material.getClassName();
-        switch (materialCls) {
-          case 'PBRMaterial':
-            (material as PBRMaterial).albedoColor = color.toLinearSpace();
-            break;
-          case 'StandardMaterial':
-            (material as StandardMaterial).diffuseColor = color;
-            break;
-          default:
-            throw new Error(`Setting color for material of instance "${materialCls}" not implemented (yet).`);
-        }
-      }
-      return true;
-    });
-    this.parameterObservers.set(Parameter.ROUGHNESS, async payload => {
-      const roughness = Parameter.parseNumber(payload.newValue);
-      for (const material of payload.materials) {
-        const materialCls = material.getClassName();
-        switch (materialCls) {
-          case 'PBRMaterial':
-            (material as PBRMaterial).roughness = roughness;
-            break;
-          case 'StandardMaterial':
-            (material as StandardMaterial).roughness = roughness;
-            break;
-          default:
-            throw new Error(`Setting roughness for material of instance "${materialCls}" not implemented (yet).`);
-        }
-      }
-      return true;
-    });
-    this.parameterObservers.set(Parameter.METALLIC, async payload => {
-      const metallic = Parameter.parseNumber(payload.newValue);
-      for (const material of payload.materials) {
-        const materialCls = material.getClassName();
-        switch (materialCls) {
-          case 'PBRMaterial':
-            (material as PBRMaterial).metallic = metallic;
-            break;
-          default:
-            throw new Error(`Setting metallic for material of instance "${materialCls}" not implemented (yet).`);
-        }
-      }
-      return true;
-    });
-    this.parameterObservers.set(Parameter.PAINTABLE, async payload => {
-      const paintableValue: PaintableValue = Parameter.parsePaintable(payload.newValue);
-
-      // check if value is svg or image source, do the conversion accordingly
-      const srcIsSvg = isSvg(paintableValue.src);
-      if (!srcIsSvg && paintableValue.src.includes('<svg') && paintableValue.src.includes('</svg>')) {
-        // seems like the user tried to use a SVG string, as <svg> tags are used
-        // inform the user that this is not a valid SVG string
-        throw new Error(`Setting paintable value failed: "${paintableValue.src}" is no valid SVG string.`);
-      }
-
-      let imageSource: CanvasImageSource;
-      try {
-        imageSource = srcIsSvg
-          ? await createImageFromSvg(paintableValue.src)
-          : await createImageFromImgSrc(paintableValue.src);
-      } catch {
-        // SVG might be invalid, even if it passes `isSvg` check
-        // in this case the image can't be created and will throw an error, which should be handled by the viewer and
-        // Combeenation viewer control
-        throw new ViewerError({
-          id: ViewerErrorIds.InvalidParameterValue,
-          message: `Invalid value for parameter "paintable" given:\nImage can't be created from source string.\nGiven value: ${paintableValue.src}`,
-        });
-      }
-
-      // apply image source on desired material(s)
-      for (const material of payload.materials) {
-        drawPaintableOnMaterial(material, imageSource, this.viewer.scene, paintableValue.options);
-      }
-
-      return true;
-    });
-    return this;
-  }
-
-  /**
-   * Passes all {@link ParameterValue}s of the given {@link ParameterBag} for given {@link TagManagerSubject} to
-   * {@link handleParameter}.
-   * @protected
-   */
-  protected handleParameterBag(
-    subject: TagManagerSubject,
-    parameters: ParameterBag
-  ): Promise<TagManagerParameterObserverResultBag>[] {
-    const observerPromises: Promise<TagManagerParameterObserverResultBag>[] = [];
-    for (const parameter in parameters) {
-      observerPromises.push(this.handleParameter(subject, parameter, parameters[parameter]));
-    }
-    return observerPromises;
-  }
-
-  /**
-   * Asserts the given {@link Parameter} and its {@link ParameterValue}, stores the state in the {@link TagManager}'s
-   * {@link parameters}, calculates the applicable nodes, injects the {@link ParameterValue} in the node's metadata,
-   * calls the responsible {@link ParameterObserver}s and emits the event {@link Event.TAG_MANAGER_PARAMETER_COMMITTED}.
-   * @protected
-   */
-  protected async handleParameter(
-    subject: TagManagerSubject,
-    parameter: string,
-    parameterValue: ParameterValue
-  ): Promise<TagManagerParameterObserverResultBag> {
-    Parameter.assertParameter(Parameter.declarations, parameter, parameterValue);
-    const parameterBag = this.parameters.get(subject) || {};
-    const oldValue = parameterBag[parameter];
-    const parameterObserverResultBag: TagManagerParameterObserverResultBag = {
-      subject: subject,
-      parameter: parameter,
-      nodes: [],
-      materials: [],
-      oldValue: oldValue,
-      newValue: parameterValue,
-      parameterObserverResult: false,
-    };
-    if (!this.parameterObservers.has(parameter)) {
-      return Promise.resolve(parameterObserverResultBag);
-    }
-    this.parameters.set(subject, parameterBag);
-    this.parameters.get(subject)![parameter] = parameterValue;
-    // get objects by subject and filter nodes by state
-    const nodes = this.getNodesBySubject(subject).filter(
-      o => o.metadata?.tagManager?.parameters?.[parameter] !== parameterValue
-    );
-    const materials = this.getMaterialsBySubject(subject).filter(
-      o => o.metadata?.tagManager?.parameters?.[parameter] !== parameterValue
-    );
-    if (nodes.length === 0 && materials.length === 0) {
-      return Promise.resolve(parameterObserverResultBag);
-    }
-    // store state in objects
-    for (const object of [...nodes, ...materials]) {
-      injectMetadata(object, { tagManager: { parameters: { [parameter]: parameterValue } } }, false);
-    }
-
-    const observer = this.parameterObservers.get(parameter)!;
-    const result = await observer({
-      subject: subject,
-      nodes: nodes,
-      materials: materials,
-      newValue: parameterValue,
-      oldValue: oldValue,
-    });
-
-    if (result === false) {
-      // reset to old value if observer was not successful
-      this.parameters.get(subject)![parameter] = oldValue;
-      // store old state in objects
-      for (const object of [...nodes, ...materials]) {
-        injectMetadata(object, { tagManager: { parameters: { [parameter]: oldValue } } }, false);
-      }
-    }
-    parameterObserverResultBag.nodes = nodes;
-    parameterObserverResultBag.materials = materials;
-    parameterObserverResultBag.parameterObserverResult = result;
-    emitter.emit(Event.TAG_MANAGER_PARAMETER_COMMITTED, parameterObserverResultBag);
-    return parameterObserverResultBag;
-  }
-
-  /**
-   * Updates the state of the {@link TagManager}'s {@link parameters} for all new nodes and tags given in
-   * {@link TagMapping}.
-   * @protected
-   */
-  protected updateParametersWithNodeAndTagMapping(nodes: TransformNode[], tagMapping: TagMapping): void {
-    // create node mapping by linking the clone source name to the new node name
-    const nodeMapping = nodes.reduce((accNodeMapping, curNode) => {
-      const oldNode = get(curNode.metadata, 'cloneSource') as TransformNode;
-      if (oldNode) {
-        accNodeMapping[oldNode.name] = curNode.name;
-      }
-      return accNodeMapping;
-    }, {} as TagMapping);
-    for (const subject of this.parameters.keys()) {
-      const isNode = subject.nodeName;
-      const newName = isNode ? nodeMapping[subject.nodeName] : tagMapping[subject.tagName];
-      if (!newName) {
-        continue;
-      }
-      const newSubject = clone(subject);
-      newSubject[isNode ? 'nodeName' : 'tagName'] = newName;
-      const parameterBag = clone(this.parameters.get(subject)!);
-      merge(parameterBag, this.parameters.get(newSubject));
-      this.parameters.set(newSubject, parameterBag);
-    }
-  }
-}
+import { Event, emitter } from '../classes/event';
+import { FuzzyMap } from '../classes/fuzzyMap';
+import { Parameter } from '../classes/parameter';
+import { Viewer } from '../classes/viewer';
+import { ViewerError, ViewerErrorIds } from '../classes/viewerError';
+import {
+  assertMeshCapability,
+  drawPaintableOnMaterial,
+  injectMetadata,
+  mapTags,
+  setMaterial,
+} from '../util/babylonHelper';
+import { createImageFromImgSrc, createImageFromSvg } from '../util/resourceHelper';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { Tags } from '@babylonjs/core/Misc/tags';
+import isSvg from 'is-svg';
+import { clone, get, merge, uniq } from 'lodash-es';
+
+export class TagManager {
+  public readonly parameters: TagManagerParameterBag = new FuzzyMap();
+
+  public readonly parameterObservers: TagManagerParameterObserverBag = new Map();
+
+  /**
+   * Constructor.
+   */
+  public constructor(protected viewer: Viewer) {
+    this.addParameterObservers();
+  }
+
+  /**
+   * Calls the {@link ParameterObserver} for given {@link Parameter} and applies the {@link ParameterValue} on all
+   * nodes with given tagName.
+   */
+  public async setTagParameterValue(
+    tagName: string,
+    parameterName: string,
+    value: ParameterValue
+  ): Promise<TagManagerParameterObserverResultBag> {
+    return await this.handleParameter({ tagName: tagName }, parameterName, value);
+  }
+
+  /**
+   * Calls the {@link ParameterObserver} for given {@link Parameter} and applies the {@link ParameterValue} on all
+   * nodes with given nodeName.
+   */
+  public async setNodeParameterValue(
+    nodeName: string,
+    parameterName: string,
+    value: ParameterValue
+  ): Promise<TagManagerParameterObserverResultBag> {
+    return await this.handleParameter({ nodeName: nodeName }, parameterName, value);
+  }
+
+  /**
+   * Calls the {@link ParameterObserver} for given {@link Parameter} and applies the {@link ParameterValue} on all
+   * materials with given materialName.
+   */
+  public async setMaterialParameterValue(
+    materialName: string,
+    parameterName: string,
+    value: ParameterValue
+  ): Promise<TagManagerParameterObserverResultBag> {
+    return await this.handleParameter({ materialName: materialName }, parameterName, value);
+  }
+
+  /**
+   * Splits the passed {@link TagManagerParameterValue}s into individual values and calls all {@link ParameterObserver}s
+   * of all {@link Parameter}s with the respective {@link TagManagerSubject} and {@link ParameterValue}. The result is a
+   * map of passed {@link TagManagerParameterValue}s and the associated {@link TagManagerParameterObserverResult} of the
+   * {@link ParameterObserver}.
+   */
+  public async setParameterValues(
+    values: TagManagerParameterValue[]
+  ): Promise<Map<TagManagerParameterValue, TagManagerParameterObserverResultBag>> {
+    const observerResultMap: Map<TagManagerParameterValue, TagManagerParameterObserverResultBag> = new Map();
+    const tagPromises: Promise<TagManagerParameterObserverResultBag>[] = [];
+    const nodePromises: Promise<TagManagerParameterObserverResultBag>[] = [];
+    const materialPromises: Promise<TagManagerParameterObserverResultBag>[] = [];
+    for (const value of values) {
+      const subject: TagManagerSubject = {};
+      if (value.tagName) {
+        subject.tagName = value.tagName;
+      }
+      if (value.nodeName) {
+        subject.nodeName = value.nodeName;
+      }
+      if (value.materialName) {
+        subject.materialName = value.materialName;
+      }
+      const observerResultPromise = this.handleParameter(subject, value.parameterName, value.value);
+      observerResultPromise.then(result => observerResultMap.set(value, result));
+      if (value.tagName) {
+        tagPromises.push(observerResultPromise);
+      }
+      if (value.nodeName) {
+        nodePromises.push(observerResultPromise);
+      }
+      if (value.materialName) {
+        materialPromises.push(observerResultPromise);
+      }
+    }
+    await Promise.all(tagPromises);
+    await Promise.all(nodePromises);
+    await Promise.all(materialPromises);
+    return observerResultMap;
+  }
+
+  /**
+   * Gets a list of {@link TagManagerSubject}s that are present in both the state of the {@link TagManager}'s
+   * {@link parameters} and the given object.
+   */
+  public getSubjectsFor(object: TransformNode | Material): TagManagerSubject[] {
+    return [...this.parameters.keys()].filter(
+      subject =>
+        (subject.tagName && Tags.MatchesQuery(object, subject.tagName)) ||
+        (subject.nodeName && object.name === subject.nodeName) ||
+        (subject.materialName && object.name === subject.materialName)
+    );
+  }
+
+  /**
+   * Gets a list of {@link TagManagerSubject}s that are present in both the state of the {@link TagManager}'s
+   * {@link parameters} and the given objects.
+   */
+  public getApplicableSubjectsFor(objects: (TransformNode | Material)[]): TagManagerSubject[] {
+    let applicableSubjects: TagManagerSubject[] = [];
+    for (const object of objects) {
+      const subjects = this.getSubjectsFor(object);
+      applicableSubjects = [...applicableSubjects, ...subjects];
+    }
+    return uniq(applicableSubjects);
+  }
+
+  /**
+   * Applies all existing states of the {@link TagManager}'s {@link parameters} for given {@link TagManagerSubject}s.
+   */
+  public async applyExistingParameterValuesFor(
+    subjects: TagManagerSubject[]
+  ): Promise<Map<TagManagerSubject, TagManagerParameterObserverResultBag>> {
+    const observerResultMap: Map<TagManagerSubject, TagManagerParameterObserverResultBag> = new Map();
+    let tagPromises: Promise<TagManagerParameterObserverResultBag>[] = [];
+    let nodePromises: Promise<TagManagerParameterObserverResultBag>[] = [];
+    let materialPromises: Promise<TagManagerParameterObserverResultBag>[] = [];
+    for (const subject of subjects) {
+      const observerResultPromises = this.handleParameterBag(subject, this.parameters.get(subject)!);
+      for (const observerResultPromise of observerResultPromises) {
+        observerResultPromise.then(result => observerResultMap.set(subject, result));
+      }
+      if (subject.tagName) {
+        tagPromises = [...tagPromises, ...observerResultPromises];
+      }
+      if (subject.nodeName) {
+        nodePromises = [...nodePromises, ...observerResultPromises];
+      }
+      if (subject.materialName) {
+        materialPromises = [...materialPromises, ...observerResultPromises];
+      }
+    }
+    await Promise.all(tagPromises);
+    await Promise.all(nodePromises);
+    await Promise.all(materialPromises);
+    return observerResultMap;
+  }
+
+  /**
+   * Does the same as {@link setParameterValues} with the difference that all existing states of the
+   * {@link TagManager}'s {@link parameters} are applied to all given nodes.
+   */
+  public async applyExistingParameterValuesTo(
+    objects: (TransformNode | Material)[]
+  ): Promise<Map<TagManagerSubject, TagManagerParameterObserverResultBag>> {
+    return this.applyExistingParameterValuesFor(this.getApplicableSubjectsFor(objects));
+  }
+
+  /**
+   * Applies all existing states of the {@link TagManager}'s {@link parameters} for all {@link TagManagerSubject}s.
+   */
+  public async applyExistingParameterValues(): Promise<Map<TagManagerSubject, TagManagerParameterObserverResultBag>> {
+    return this.applyExistingParameterValuesFor([...this.parameters.keys()]);
+  }
+
+  /**
+   * Maps all tags on given nodes with the {@link TagMapping} and updates the state of the {@link TagManager}'s
+   * {@link parameters} for all new tags.
+   * Also updates the state of all nodes in the tag managers parameter state.
+   */
+  public mapNodesAndTags(nodes: TransformNode[], tagMapping: TagMapping): TagManager {
+    this.updateParametersWithNodeAndTagMapping(nodes, tagMapping);
+    mapTags(nodes, tagMapping);
+    return this;
+  }
+
+  /**
+   * Gets a distinct list of all tags within the current scene.
+   */
+  public getAllTags(): string[] {
+    const tags: string[] = [];
+    const nodes = this.viewer.scene.getNodes();
+    for (const node of nodes) {
+      tags.push(...Object.keys(Tags.GetTags(node, false) ?? {}));
+    }
+    return [...new Set(tags)];
+  }
+
+  /**
+   * Prints the state of the {@link TagManager}'s {@link parameters} to the console.
+   */
+  public printAllTags(): void {
+    const printable = [];
+    for (const subject of this.parameters.keys()) {
+      const parameterBag = this.parameters.get(subject);
+      for (const parameter in parameterBag) {
+        printable.push({
+          subject: JSON.stringify(subject),
+          parameter: parameter,
+          value: parameterBag[parameter],
+          nodes: this.getNodesBySubject(subject),
+        });
+      }
+    }
+    console.table(printable);
+  }
+
+  /**
+   * Prints the state of the {@link TagManager}'s {@link parameters} for one tagName to the console.
+   */
+  public printTagInfo(tagName: string): void {
+    const parameterBag = this.parameters.get({ tagName: tagName });
+    const printable = [];
+    for (const parameter in parameterBag) {
+      printable.push({
+        parameter: parameter,
+        value: parameterBag[parameter],
+        nodes: this.getNodesBySubject({ tagName: tagName }),
+      });
+    }
+    console.table(printable);
+  }
+
+  /**
+   * Sets a {@link ParameterObserver} for the given {@link Parameter}.
+   *
+   * The observer should return `false` in cases where the given value was not actually applied. E.g. when wanting to
+   * apply a property on the given `node`s material which doesn't exist at the time the observer is called etc.
+   */
+  public setParameterObserver(parameter: string, observer: TagManagerParameterObserver): TagManager {
+    this.parameterObservers.set(parameter, observer);
+    return this;
+  }
+
+  /**
+   * Gets all nodes for given {@link TagManagerSubject} on the Babylon.js scene.
+   */
+  public getNodesBySubject(subject: TagManagerSubject, predicate?: (node: TransformNode) => boolean): TransformNode[] {
+    let nodes: TransformNode[] = [];
+    if (subject.tagName) {
+      nodes = [
+        ...nodes,
+        ...this.viewer.scene.getTransformNodesByTags(subject.tagName, predicate),
+        ...this.viewer.scene.getMeshesByTags(subject.tagName, predicate),
+      ];
+    }
+    if (subject.nodeName) {
+      nodes = [
+        ...nodes,
+        this.viewer.scene.getTransformNodeByName(subject.nodeName),
+        this.viewer.scene.getMeshByName(subject.nodeName),
+      ].filter(t => !!t && (!predicate || predicate(t))) as TransformNode[];
+    }
+    return nodes;
+  }
+
+  /**
+   * Gets all materials for given {@link TagManagerSubject} on the Babylon.js scene.
+   */
+  public getMaterialsBySubject(subject: TagManagerSubject, predicate?: (material: Material) => boolean): Material[] {
+    let materials: Material[] = [];
+    if (subject.tagName) {
+      materials = [...materials, ...this.viewer.scene.getMaterialByTags(subject.tagName, predicate)];
+    }
+    if (subject.materialName) {
+      materials = [...materials, this.viewer.scene.getMaterialByName(subject.materialName)].filter(
+        t => !!t && (!predicate || predicate(t))
+      ) as Material[];
+    }
+    return materials;
+  }
+
+  /**
+   * Registers observers that are called on every new object added to the Babylon.js scene.
+   * The observers ensure that each new object gets the state of the {@link TagManager}'s {@link parameters} applied.
+   */
+  public registerNewObjectObservers(scene: Scene) {
+    // nodes and meshes
+    const onNewTransformNodeAdded = (node: TransformNode) => {
+      /* NOTE:
+         Removed the check for created instances here since it is not guaranteed that all instances
+         created means that there is no scenario where new nodes should get TagManager parameters applied.
+         Instead, we check for the state to be enabled via the `onEnabledStateChangedObservable` below.
+       */
+      const onEnabledStateChangedObserver = node.onEnabledStateChangedObservable.add(async state => {
+        if (!state) {
+          // if the node is disabled, means ignoring also "ghost nodes"
+          return;
+        }
+        await this.applyExistingParameterValuesTo([node]);
+        node.onEnabledStateChangedObservable.remove(onEnabledStateChangedObserver);
+      });
+      node.onEnabledStateChangedObservable.makeObserverBottomPriority(onEnabledStateChangedObserver!);
+    };
+    scene.onNewTransformNodeAddedObservable.makeObserverBottomPriority(
+      scene.onNewTransformNodeAddedObservable.add(onNewTransformNodeAdded)!
+    );
+    scene.onNewMeshAddedObservable.makeObserverBottomPriority(
+      scene.onNewMeshAddedObservable.add(onNewTransformNodeAdded)!
+    );
+    // materials
+    const onNewMaterialAdded = (material: Material) => {
+      /* NOTE:
+				 We have to wait until a material is bound to a Mesh. In all other scenarios, the material
+				 is not "fully ready" or even empty (without working attributes/properties).
+			 */
+      const onMaterialBindObserver = material.onBindObservable.add(async abstractMesh => {
+        await this.applyExistingParameterValuesTo([material]);
+        material.onBindObservable.remove(onMaterialBindObserver);
+      });
+      material.onBindObservable.makeObserverBottomPriority(onMaterialBindObserver!);
+    };
+    scene.onNewMaterialAddedObservable.makeObserverBottomPriority(
+      scene.onNewMaterialAddedObservable.add(onNewMaterialAdded)!
+    );
+  }
+
+  /**
+   * Adds the default {@link ParameterObserver}s.
+   * @protected
+   */
+  protected addParameterObservers(): TagManager {
+    this.parameterObservers.set(Parameter.VISIBLE, async payload => {
+      const visible = Parameter.parseBoolean(payload.newValue);
+      if (visible === true) {
+        for (const node of payload.nodes) {
+          node.setEnabled(true);
+        }
+      } else if (visible === false) {
+        for (const node of payload.nodes) {
+          node.setEnabled(false);
+        }
+      }
+      return true;
+    });
+    this.parameterObservers.set(Parameter.SCALING, async payload => {
+      for (const node of payload.nodes) {
+        node.scaling = Parameter.parseVector(payload.newValue);
+      }
+      return true;
+    });
+    this.parameterObservers.set(Parameter.POSITION, async payload => {
+      for (const node of payload.nodes) {
+        node.position = Parameter.parseVector(payload.newValue);
+      }
+      return true;
+    });
+    this.parameterObservers.set(Parameter.ROTATION, async payload => {
+      for (const node of payload.nodes) {
+        node.rotation = Parameter.parseRotation(payload.newValue);
+      }
+      return true;
+    });
+    this.parameterObservers.set(Parameter.MATERIAL, async payload => {
+      for (const node of payload.nodes) {
+        assertMeshCapability(node, Parameter.MATERIAL);
+        setMaterial(node, payload.newValue.toString(), false);
+      }
+      return true;
+    });
+    this.parameterObservers.set(Parameter.COLOR, async payload => {
+      const color = Parameter.parseColor(payload.newValue);
+      for (const material of payload.materials) {
+        const materialCls = material.getClassName();
+        switch (materialCls) {
+          case 'PBRMaterial':
+            (material as PBRMaterial).albedoColor = color.toLinearSpace();
+            break;
+          case 'StandardMaterial':
+            (material as StandardMaterial).diffuseColor = color;
+            break;
+          default:
+            throw new Error(`Setting color for material of instance "${materialCls}" not implemented (yet).`);
+        }
+      }
+      return true;
+    });
+    this.parameterObservers.set(Parameter.ROUGHNESS, async payload => {
+      const roughness = Parameter.parseNumber(payload.newValue);
+      for (const material of payload.materials) {
+        const materialCls = material.getClassName();
+        switch (materialCls) {
+          case 'PBRMaterial':
+            (material as PBRMaterial).roughness = roughness;
+            break;
+          case 'StandardMaterial':
+            (material as StandardMaterial).roughness = roughness;
+            break;
+          default:
+            throw new Error(`Setting roughness for material of instance "${materialCls}" not implemented (yet).`);
+        }
+      }
+      return true;
+    });
+    this.parameterObservers.set(Parameter.METALLIC, async payload => {
+      const metallic = Parameter.parseNumber(payload.newValue);
+      for (const material of payload.materials) {
+        const materialCls = material.getClassName();
+        switch (materialCls) {
+          case 'PBRMaterial':
+            (material as PBRMaterial).metallic = metallic;
+            break;
+          default:
+            throw new Error(`Setting metallic for material of instance "${materialCls}" not implemented (yet).`);
+        }
+      }
+      return true;
+    });
+    this.parameterObservers.set(Parameter.PAINTABLE, async payload => {
+      const paintableValue: PaintableValue = Parameter.parsePaintable(payload.newValue);
+
+      // check if value is svg or image source, do the conversion accordingly
+      const srcIsSvg = isSvg(paintableValue.src);
+      if (!srcIsSvg && paintableValue.src.includes('<svg') && paintableValue.src.includes('</svg>')) {
+        // seems like the user tried to use a SVG string, as <svg> tags are used
+        // inform the user that this is not a valid SVG string
+        throw new Error(`Setting paintable value failed: "${paintableValue.src}" is no valid SVG string.`);
+      }
+
+      let imageSource: CanvasImageSource;
+      try {
+        imageSource = srcIsSvg
+          ? await createImageFromSvg(paintableValue.src)
+          : await createImageFromImgSrc(paintableValue.src);
+      } catch {
+        // SVG might be invalid, even if it passes `isSvg` check
+        // in this case the image can't be created and will throw an error, which should be handled by the viewer and
+        // Combeenation viewer control
+        throw new ViewerError({
+          id: ViewerErrorIds.InvalidParameterValue,
+          message: `Invalid value for parameter "paintable" given:\nImage can't be created from source string.\nGiven value: ${paintableValue.src}`,
+        });
+      }
+
+      // apply image source on desired material(s)
+      for (const material of payload.materials) {
+        drawPaintableOnMaterial(material, imageSource, this.viewer.scene, paintableValue.options);
+      }
+
+      return true;
+    });
+    return this;
+  }
+
+  /**
+   * Passes all {@link ParameterValue}s of the given {@link ParameterBag} for given {@link TagManagerSubject} to
+   * {@link handleParameter}.
+   * @protected
+   */
+  protected handleParameterBag(
+    subject: TagManagerSubject,
+    parameters: ParameterBag
+  ): Promise<TagManagerParameterObserverResultBag>[] {
+    const observerPromises: Promise<TagManagerParameterObserverResultBag>[] = [];
+    for (const parameter in parameters) {
+      observerPromises.push(this.handleParameter(subject, parameter, parameters[parameter]));
+    }
+    return observerPromises;
+  }
+
+  /**
+   * Asserts the given {@link Parameter} and its {@link ParameterValue}, stores the state in the {@link TagManager}'s
+   * {@link parameters}, calculates the applicable nodes, injects the {@link ParameterValue} in the node's metadata,
+   * calls the responsible {@link ParameterObserver}s and emits the event {@link Event.TAG_MANAGER_PARAMETER_COMMITTED}.
+   * @protected
+   */
+  protected async handleParameter(
+    subject: TagManagerSubject,
+    parameter: string,
+    parameterValue: ParameterValue
+  ): Promise<TagManagerParameterObserverResultBag> {
+    Parameter.assertParameter(Parameter.declarations, parameter, parameterValue);
+    const parameterBag = this.parameters.get(subject) || {};
+    const oldValue = parameterBag[parameter];
+    const parameterObserverResultBag: TagManagerParameterObserverResultBag = {
+      subject: subject,
+      parameter: parameter,
+      nodes: [],
+      materials: [],
+      oldValue: oldValue,
+      newValue: parameterValue,
+      parameterObserverResult: false,
+    };
+    if (!this.parameterObservers.has(parameter)) {
+      return Promise.resolve(parameterObserverResultBag);
+    }
+    this.parameters.set(subject, parameterBag);
+    this.parameters.get(subject)![parameter] = parameterValue;
+    // get objects by subject and filter nodes by state
+    const nodes = this.getNodesBySubject(subject).filter(
+      o => o.metadata?.tagManager?.parameters?.[parameter] !== parameterValue
+    );
+    const materials = this.getMaterialsBySubject(subject).filter(
+      o => o.metadata?.tagManager?.parameters?.[parameter] !== parameterValue
+    );
+    if (nodes.length === 0 && materials.length === 0) {
+      return Promise.resolve(parameterObserverResultBag);
+    }
+    // store state in objects
+    for (const object of [...nodes, ...materials]) {
+      injectMetadata(object, { tagManager: { parameters: { [parameter]: parameterValue } } }, false);
+    }
+
+    const observer = this.parameterObservers.get(parameter)!;
+    const result = await observer({
+      subject: subject,
+      nodes: nodes,
+      materials: materials,
+      newValue: parameterValue,
+      oldValue: oldValue,
+    });
+
+    if (result === false) {
+      // reset to old value if observer was not successful
+      this.parameters.get(subject)![parameter] = oldValue;
+      // store old state in objects
+      for (const object of [...nodes, ...materials]) {
+        injectMetadata(object, { tagManager: { parameters: { [parameter]: oldValue } } }, false);
+      }
+    }
+    parameterObserverResultBag.nodes = nodes;
+    parameterObserverResultBag.materials = materials;
+    parameterObserverResultBag.parameterObserverResult = result;
+    emitter.emit(Event.TAG_MANAGER_PARAMETER_COMMITTED, parameterObserverResultBag);
+    return parameterObserverResultBag;
+  }
+
+  /**
+   * Updates the state of the {@link TagManager}'s {@link parameters} for all new nodes and tags given in
+   * {@link TagMapping}.
+   * @protected
+   */
+  protected updateParametersWithNodeAndTagMapping(nodes: TransformNode[], tagMapping: TagMapping): void {
+    // create node mapping by linking the clone source name to the new node name
+    const nodeMapping = nodes.reduce((accNodeMapping, curNode) => {
+      const oldNode = get(curNode.metadata, 'cloneSource') as TransformNode;
+      if (oldNode) {
+        accNodeMapping[oldNode.name] = curNode.name;
+      }
+      return accNodeMapping;
+    }, {} as TagMapping);
+    for (const subject of this.parameters.keys()) {
+      const isNode = subject.nodeName;
+      const newName = isNode ? nodeMapping[subject.nodeName] : tagMapping[subject.tagName];
+      if (!newName) {
+        continue;
+      }
+      const newSubject = clone(subject);
+      newSubject[isNode ? 'nodeName' : 'tagName'] = newName;
+      const parameterBag = clone(this.parameters.get(subject)!);
+      merge(parameterBag, this.parameters.get(newSubject));
+      this.parameters.set(newSubject, parameterBag);
+    }
+  }
+}