@combeenation/3d-viewer 7.1.3 → 8.0.0

package/src/api/manager/tagManager.ts

@@ -1,477 +1,477 @@
-import { Event, emitter } from '../classes/event';
-import { FuzzyMap } from '../classes/fuzzyMap';
-import { Parameter } from '../classes/parameter';
-import { Viewer } from '../classes/viewer';
-import {
-  assertMeshCapability,
-  cloneTransformNodeMaterial,
-  injectNodeMetadata,
-  mapTags,
-  setMaterial,
-  setMaterialColor,
-  setMaterialMetallness,
-  setMaterialRoughness,
-} from '../util/babylonHelper';
-import { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
-import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
-import { Tags } from '@babylonjs/core/Misc/tags';
-import { clone, get, has, 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<ParameterObserverResult> {
-    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<ParameterObserverResult> {
-    return await this.handleParameter({ nodeName: nodeName }, 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 ParameterObserverResult} of the
-   * {@link ParameterObserver}.
-   */
-  public async setParameterValues(
-    values: TagManagerParameterValue[]
-  ): Promise<Map<TagManagerParameterValue, ParameterObserverResult>> {
-    const observerResultMap: Map<TagManagerParameterValue, ParameterObserverResult> = new Map();
-    const tagPromises: Promise<ParameterObserverResult>[] = [];
-    const nodePromises: Promise<ParameterObserverResult>[] = [];
-    for (const value of values) {
-      const subject: TagManagerSubject = {};
-      if (value.tagName) {
-        subject.tagName = value.tagName;
-      }
-      if (value.nodeName) {
-        subject.nodeName = value.nodeName;
-      }
-      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);
-      }
-    }
-    await Promise.all(tagPromises);
-    await Promise.all(nodePromises);
-    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 node.
-   */
-  public getSubjectsFor(node: TransformNode): TagManagerSubject[] {
-    return [...this.parameters.keys()].filter(
-      subject =>
-        (subject.tagName && Tags.MatchesQuery(node, subject.tagName)) ||
-        (subject.nodeName && node.name === subject.nodeName)
-    );
-  }
-
-  /**
-   * Gets a list of {@link TagManagerSubject}s that are present in both the state of the {@link TagManager}'s
-   * {@link parameters} and the given nodes.
-   */
-  public getApplicableSubjectsFor(nodes: TransformNode[]): TagManagerSubject[] {
-    let applicableSubjects: TagManagerSubject[] = [];
-    for (const node of nodes) {
-      const subjects = this.getSubjectsFor(node);
-      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, ParameterObserverResult>> {
-    const observerResultMap: Map<TagManagerSubject, ParameterObserverResult> = new Map();
-    let tagPromises: Promise<ParameterObserverResult>[] = [];
-    let nodePromises: Promise<ParameterObserverResult>[] = [];
-    for (const subject of subjects) {
-      this.clearAppliedNodeMetadataParameters(this.getNodesBySubject(subject));
-      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];
-      }
-    }
-    await Promise.all(tagPromises);
-    await Promise.all(nodePromises);
-    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(
-    nodes: TransformNode[]
-  ): Promise<Map<TagManagerSubject, ParameterObserverResult>> {
-    return this.applyExistingParameterValuesFor(this.getApplicableSubjectsFor(nodes));
-  }
-
-  /**
-   * Applies all existing states of the {@link TagManager}'s {@link parameters} for all {@link TagManagerSubject}s.
-   */
-  public async applyExistingParameterValues(): Promise<Map<TagManagerSubject, ParameterObserverResult>> {
-    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;
-  }
-
-  /**
-   * Registers observers that are called on every new node added to the Babylon.js scene. The observers ensure that each
-   * new node gets the state of the {@link TagManager}'s {@link parameters} applied.
-   */
-  public registerNewTransformNodeObservers(scene: Scene) {
-    const onNewTransformNodeAdded = (node: TransformNode) => {
-      if (node.name === Viewer.BOUNDING_BOX_NAME || !this.viewer.variantInstances.areAllDefinitionsCreated) {
-        // Avoid duplicate calls here. The parameter values are already applied when a variant instance has finished
-        // creating (see event listener in viewer for VARIANT_INSTANCE_CREATED). This callback should only trigger when
-        // a consumer "manually" clones a node.
-        return;
-      }
-      this.applyExistingParameterValuesTo([node]).then();
-    };
-    scene.onNewTransformNodeAddedObservable.makeObserverBottomPriority(
-      scene.onNewTransformNodeAddedObservable.add(onNewTransformNodeAdded)!
-    );
-    scene.onNewMeshAddedObservable.makeObserverBottomPriority(
-      scene.onNewMeshAddedObservable.add(onNewTransformNodeAdded)!
-    );
-  }
-
-  /**
-   * Adds the default {@link ParameterObserver}s.
-   * @protected
-   */
-  protected addParameterObservers(): TagManager {
-    this.parameterObservers.set(Parameter.VISIBLE, async payload => {
-      let visible;
-      try {
-        visible = Parameter.parseBoolean(payload.newValue);
-      } catch (e) {
-        return false;
-      }
-      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.MATERIAL_COLOR, async payload => {
-      const parsedValue = Parameter.parseColor(payload.newValue);
-      for (const node of payload.nodes) {
-        assertMeshCapability(node, Parameter.MATERIAL_COLOR);
-        if (this.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: payload.oldValue } } }, false);
-          }
-        }
-        setMaterialColor(node, parsedValue, false);
-      }
-      return true;
-    });
-    this.parameterObservers.set(Parameter.MATERIAL_ROUGHNESS, async payload => {
-      const parsedValue = Parameter.parseNumber(payload.newValue);
-      for (const node of payload.nodes as AbstractMesh[]) {
-        assertMeshCapability(node, Parameter.MATERIAL_ROUGHNESS);
-        if (this.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: { color: payload.oldValue } } }, false);
-          }
-        }
-        setMaterialRoughness(node, parsedValue, false);
-      }
-      return true;
-    });
-    this.parameterObservers.set(Parameter.MATERIAL_METALLNESS, async payload => {
-      const parsedValue = Parameter.parseNumber(payload.newValue);
-      for (const node of payload.nodes as AbstractMesh[]) {
-        assertMeshCapability(node, Parameter.MATERIAL_METALLNESS);
-        if (this.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: { color: payload.oldValue } } }, false);
-          }
-        }
-        setMaterialMetallness(node, parsedValue, false);
-      }
-      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<ParameterObserverResult>[] {
-    const observerPromises: Promise<ParameterObserverResult>[] = [];
-    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<ParameterObserverResult> {
-    Parameter.assertParameter(Parameter.declarations, parameter, parameterValue);
-    if (!this.parameterObservers.has(parameter)) {
-      return Promise.resolve(false);
-    }
-    const parameterBag = this.parameters.get(subject) || {};
-    const oldValue = parameterBag[parameter];
-    if (oldValue === parameterValue) {
-      return Promise.resolve(false);
-    }
-    this.parameters.set(subject, parameterBag);
-    this.parameters.get(subject)![parameter] = parameterValue;
-    const nodes = this.getNodesBySubject(subject);
-    if (nodes.length === 0) {
-      return Promise.resolve(false);
-    }
-    const observer = this.parameterObservers.get(parameter)!;
-    const result = await observer({ subject: subject, nodes: nodes, newValue: parameterValue, oldValue: oldValue });
-    if (result === false) {
-      // reset to old value if observer was not successful
-      this.parameters.get(subject)![parameter] = oldValue;
-    }
-    emitter.emit(Event.TAG_MANAGER_PARAMETER_COMMITTED, {
-      subject: subject,
-      parameter: parameter,
-      nodes: nodes,
-      oldValue: oldValue,
-      newValue: parameterValue,
-      result: result,
-    });
-  }
-
-  /**
-   * 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);
-    }
-  }
-
-  /**
-   * Clears the applied {@link ParameterBag} state of the node's metadata to ensure that observers trigger (once again).
-   * This is necessary e.g. after mapping tags when a nodeName subject shall override the parameterValue of a mapped
-   * tag.
-   * @protected
-   */
-  protected clearAppliedNodeMetadataParameters(nodes: TransformNode[]): void {
-    for (const node of nodes) {
-      if (!node.metadata?.tagManager?.parameters) {
-        continue;
-      }
-      node.metadata.tagManager.parameters = {};
-    }
-  }
-}
+import { Event, emitter } from '../classes/event';
+import { FuzzyMap } from '../classes/fuzzyMap';
+import { Parameter } from '../classes/parameter';
+import { Viewer } from '../classes/viewer';
+import {
+  assertMeshCapability,
+  cloneTransformNodeMaterial,
+  injectNodeMetadata,
+  mapTags,
+  setMaterial,
+  setMaterialColor,
+  setMaterialMetallness,
+  setMaterialRoughness,
+} from '../util/babylonHelper';
+import { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { Tags } from '@babylonjs/core/Misc/tags';
+import { clone, get, has, 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<ParameterObserverResult> {
+    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<ParameterObserverResult> {
+    return await this.handleParameter({ nodeName: nodeName }, 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 ParameterObserverResult} of the
+   * {@link ParameterObserver}.
+   */
+  public async setParameterValues(
+    values: TagManagerParameterValue[]
+  ): Promise<Map<TagManagerParameterValue, ParameterObserverResult>> {
+    const observerResultMap: Map<TagManagerParameterValue, ParameterObserverResult> = new Map();
+    const tagPromises: Promise<ParameterObserverResult>[] = [];
+    const nodePromises: Promise<ParameterObserverResult>[] = [];
+    for (const value of values) {
+      const subject: TagManagerSubject = {};
+      if (value.tagName) {
+        subject.tagName = value.tagName;
+      }
+      if (value.nodeName) {
+        subject.nodeName = value.nodeName;
+      }
+      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);
+      }
+    }
+    await Promise.all(tagPromises);
+    await Promise.all(nodePromises);
+    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 node.
+   */
+  public getSubjectsFor(node: TransformNode): TagManagerSubject[] {
+    return [...this.parameters.keys()].filter(
+      subject =>
+        (subject.tagName && Tags.MatchesQuery(node, subject.tagName)) ||
+        (subject.nodeName && node.name === subject.nodeName)
+    );
+  }
+
+  /**
+   * Gets a list of {@link TagManagerSubject}s that are present in both the state of the {@link TagManager}'s
+   * {@link parameters} and the given nodes.
+   */
+  public getApplicableSubjectsFor(nodes: TransformNode[]): TagManagerSubject[] {
+    let applicableSubjects: TagManagerSubject[] = [];
+    for (const node of nodes) {
+      const subjects = this.getSubjectsFor(node);
+      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, ParameterObserverResult>> {
+    const observerResultMap: Map<TagManagerSubject, ParameterObserverResult> = new Map();
+    let tagPromises: Promise<ParameterObserverResult>[] = [];
+    let nodePromises: Promise<ParameterObserverResult>[] = [];
+    for (const subject of subjects) {
+      this.clearAppliedNodeMetadataParameters(this.getNodesBySubject(subject));
+      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];
+      }
+    }
+    await Promise.all(tagPromises);
+    await Promise.all(nodePromises);
+    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(
+    nodes: TransformNode[]
+  ): Promise<Map<TagManagerSubject, ParameterObserverResult>> {
+    return this.applyExistingParameterValuesFor(this.getApplicableSubjectsFor(nodes));
+  }
+
+  /**
+   * Applies all existing states of the {@link TagManager}'s {@link parameters} for all {@link TagManagerSubject}s.
+   */
+  public async applyExistingParameterValues(): Promise<Map<TagManagerSubject, ParameterObserverResult>> {
+    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;
+  }
+
+  /**
+   * Registers observers that are called on every new node added to the Babylon.js scene. The observers ensure that each
+   * new node gets the state of the {@link TagManager}'s {@link parameters} applied.
+   */
+  public registerNewTransformNodeObservers(scene: Scene) {
+    const onNewTransformNodeAdded = (node: TransformNode) => {
+      if (node.name === Viewer.BOUNDING_BOX_NAME || !this.viewer.variantInstances.areAllDefinitionsCreated) {
+        // Avoid duplicate calls here. The parameter values are already applied when a variant instance has finished
+        // creating (see event listener in viewer for VARIANT_INSTANCE_CREATED). This callback should only trigger when
+        // a consumer "manually" clones a node.
+        return;
+      }
+      this.applyExistingParameterValuesTo([node]).then();
+    };
+    scene.onNewTransformNodeAddedObservable.makeObserverBottomPriority(
+      scene.onNewTransformNodeAddedObservable.add(onNewTransformNodeAdded)!
+    );
+    scene.onNewMeshAddedObservable.makeObserverBottomPriority(
+      scene.onNewMeshAddedObservable.add(onNewTransformNodeAdded)!
+    );
+  }
+
+  /**
+   * Adds the default {@link ParameterObserver}s.
+   * @protected
+   */
+  protected addParameterObservers(): TagManager {
+    this.parameterObservers.set(Parameter.VISIBLE, async payload => {
+      let visible;
+      try {
+        visible = Parameter.parseBoolean(payload.newValue);
+      } catch (e) {
+        return false;
+      }
+      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.MATERIAL_COLOR, async payload => {
+      const parsedValue = Parameter.parseColor(payload.newValue);
+      for (const node of payload.nodes) {
+        assertMeshCapability(node, Parameter.MATERIAL_COLOR);
+        if (this.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: payload.oldValue } } }, false);
+          }
+        }
+        setMaterialColor(node, parsedValue, false);
+      }
+      return true;
+    });
+    this.parameterObservers.set(Parameter.MATERIAL_ROUGHNESS, async payload => {
+      const parsedValue = Parameter.parseNumber(payload.newValue);
+      for (const node of payload.nodes as AbstractMesh[]) {
+        assertMeshCapability(node, Parameter.MATERIAL_ROUGHNESS);
+        if (this.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: { color: payload.oldValue } } }, false);
+          }
+        }
+        setMaterialRoughness(node, parsedValue, false);
+      }
+      return true;
+    });
+    this.parameterObservers.set(Parameter.MATERIAL_METALLNESS, async payload => {
+      const parsedValue = Parameter.parseNumber(payload.newValue);
+      for (const node of payload.nodes as AbstractMesh[]) {
+        assertMeshCapability(node, Parameter.MATERIAL_METALLNESS);
+        if (this.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: { color: payload.oldValue } } }, false);
+          }
+        }
+        setMaterialMetallness(node, parsedValue, false);
+      }
+      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<ParameterObserverResult>[] {
+    const observerPromises: Promise<ParameterObserverResult>[] = [];
+    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<ParameterObserverResult> {
+    Parameter.assertParameter(Parameter.declarations, parameter, parameterValue);
+    if (!this.parameterObservers.has(parameter)) {
+      return Promise.resolve(false);
+    }
+    const parameterBag = this.parameters.get(subject) || {};
+    const oldValue = parameterBag[parameter];
+    if (oldValue === parameterValue) {
+      return Promise.resolve(false);
+    }
+    this.parameters.set(subject, parameterBag);
+    this.parameters.get(subject)![parameter] = parameterValue;
+    const nodes = this.getNodesBySubject(subject);
+    if (nodes.length === 0) {
+      return Promise.resolve(false);
+    }
+    const observer = this.parameterObservers.get(parameter)!;
+    const result = await observer({ subject: subject, nodes: nodes, newValue: parameterValue, oldValue: oldValue });
+    if (result === false) {
+      // reset to old value if observer was not successful
+      this.parameters.get(subject)![parameter] = oldValue;
+    }
+    emitter.emit(Event.TAG_MANAGER_PARAMETER_COMMITTED, {
+      subject: subject,
+      parameter: parameter,
+      nodes: nodes,
+      oldValue: oldValue,
+      newValue: parameterValue,
+      result: result,
+    });
+  }
+
+  /**
+   * 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);
+    }
+  }
+
+  /**
+   * Clears the applied {@link ParameterBag} state of the node's metadata to ensure that observers trigger (once again).
+   * This is necessary e.g. after mapping tags when a nodeName subject shall override the parameterValue of a mapped
+   * tag.
+   * @protected
+   */
+  protected clearAppliedNodeMetadataParameters(nodes: TransformNode[]): void {
+    for (const node of nodes) {
+      if (!node.metadata?.tagManager?.parameters) {
+        continue;
+      }
+      node.metadata.tagManager.parameters = {};
+    }
+  }
+}