@combeenation/3d-viewer 6.5.0 → 7.0.0-beta1

package/src/api/manager/tagManager.ts

@@ -0,0 +1,451 @@
+import { Event, emitter } from '../classes/event';
+import { FuzzyMap } from '../classes/fuzzyMap';
+import { Parameter } from '../classes/parameter';
+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<ParameterObserver>[] = [];
+    const nodePromises: Promise<ParameterObserver>[] = [];
+    for (const value of values) {
+      const subject: TagManagerSubject = {};
+      if (value.tagName) {
+        subject.tagName = value.tagName;
+      }
+      if (value.nodeName) {
+        subject.nodeName = value.nodeName;
+      }
+      const promise = this.handleParameter(subject, value.parameterName, value.value);
+      promise.then(result => observerResultMap.set(value, result));
+      if (value.tagName) {
+        tagPromises.push(promise);
+      }
+      if (value.nodeName) {
+        nodePromises.push(promise);
+      }
+    }
+    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<ParameterObserver>[] = [];
+    let nodePromises: Promise<ParameterObserver>[] = [];
+    for (const subject of subjects) {
+      this.clearAppliedNodeMetadataParameters(this.getNodesBySubject(subject));
+      const promises = this.handleParameterBag(subject, this.parameters.get(subject)!);
+      for (const promise of promises) {
+        promise.then(result => observerResultMap.set(subject, result));
+      }
+      if (subject.tagName) {
+        tagPromises = [...tagPromises, ...promises];
+      }
+      if (subject.nodeName) {
+        nodePromises = [...nodePromises, ...promises];
+      }
+    }
+    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;
+  }
+
+  /**
+   * 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}.
+   */
+  public setParameterObserver(parameter: string, observer: TagManagerParameterObserver): TagManager {
+    this.parameterObservers.set(parameter, observer);
+    return this;
+  }
+
+  /**
+   * Gets all nodes for given {@link TagManagerSubject} on the Babylon 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 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 = async (node: TransformNode) => {
+      await this.viewer.scene.whenReadyAsync();
+      await this.applyExistingParameterValuesTo([node]);
+    };
+    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;
+      }
+      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 payload;
+    });
+    this.parameterObservers.set(Parameter.SCALING, async payload => {
+      for (const node of payload.nodes) {
+        node.scaling = Parameter.parseVector(payload.newValue);
+      }
+      return payload;
+    });
+    this.parameterObservers.set(Parameter.POSITION, async payload => {
+      for (const node of payload.nodes) {
+        node.position = Parameter.parseVector(payload.newValue);
+      }
+      return payload;
+    });
+    this.parameterObservers.set(Parameter.ROTATION, async payload => {
+      for (const node of payload.nodes) {
+        node.rotation = Parameter.parseRotation(payload.newValue);
+      }
+      return payload;
+    });
+    this.parameterObservers.set(Parameter.MATERIAL, async payload => {
+      for (const node of payload.nodes) {
+        assertMeshCapability(node, Parameter.MATERIAL);
+        setMaterial(node, payload.newValue.toString(), false);
+      }
+      return payload;
+    });
+    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 payload;
+    });
+    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 payload;
+    });
+    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 payload;
+    });
+    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<ParameterObserver>[] {
+    const observerPromises: Promise<ParameterObserver>[] = [];
+    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 handleParameter(
+    subject: TagManagerSubject,
+    parameter: string,
+    parameterValue: ParameterValue
+  ): Promise<ParameterObserver> {
+    Parameter.assertParameter(Parameter.declarations, parameter, parameterValue);
+    if (!this.parameterObservers.has(parameter)) {
+      return Promise.resolve(() => undefined);
+    }
+    const parameterBag = this.parameters.get(subject) || {};
+    const oldValue = parameterBag[parameter];
+    this.parameters.set(subject, parameterBag);
+    this.parameters.get(subject)![parameter] = parameterValue;
+    const predicate = (node: TransformNode) => node.metadata?.tagManager?.parameters[parameter] !== parameterValue;
+    const nodes = this.getNodesBySubject(subject, predicate);
+    if (nodes.length === 0) {
+      return Promise.resolve(() => undefined);
+    }
+    for (const node of nodes) {
+      injectNodeMetadata(node, { tagManager: { parameters: { [parameter]: parameterValue } } }, false);
+    }
+    const observer = this.parameterObservers.get(parameter)!;
+    const observerResult = observer({ subject: subject, nodes: nodes, newValue: parameterValue, oldValue: oldValue });
+    return Promise.resolve(observerResult).then(result => {
+      emitter.emit(Event.TAG_MANAGER_PARAMETER_COMMITTED, {
+        subject: subject,
+        parameter: parameter,
+        value: parameterValue,
+        nodes: nodes,
+        result: result,
+      });
+    }) as Promise<ParameterObserver>;
+  }
+
+  /**
+   * 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 = {};
+    }
+  }
+}

package/src/api/manager/variantInstanceManager.ts

@@ -4,6 +4,9 @@ import { EventBroadcaster } from '../classes/eventBroadcaster';
 import { Parameter } from '../classes/parameter';
 import { Variant } from '../classes/variant';
 import { VariantInstance } from '../classes/variantInstance';
+import { SpecStorage } from '../store/specStorage';
+import { duplicateNodeNames, reportDuplicateNodeNames } from '../util/babylonHelper';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
 import { merge } from 'lodash-es';
 
 /**
@@ -24,15 +27,16 @@ export class VariantInstanceManager extends EventBroadcaster {
   /**
    * Constructor.
    */
-  protected constructor(protected rootVariant: Variant) {
+  protected constructor(public viewer: Viewer, protected rootVariant: Variant) {
     super();
   }
 
   /**
    * Creates a {@link VariantInstanceManager} based on given root Variant.
    */
-  public static async create(rootVariant: Variant): Promise<VariantInstanceManager> {
-    return new VariantInstanceManager(rootVariant);
+  public static async create(viewer: Viewer): Promise<VariantInstanceManager> {
+    const rootVariant = await Variant.createRoot(SpecStorage.getSpec(), viewer);
+    return new VariantInstanceManager(viewer, rootVariant);
   }
 
   /**
@@ -53,6 +57,13 @@ export class VariantInstanceManager extends EventBroadcaster {
     return all;
   }
 
+  /**
+   * Gets all {@link VariantInstance}s with given {@link Variant}'s name.
+   */
+  public allWithVariantName(name: string): VariantInstance[] {
+    return this.all.filter(instance => instance.variant.name === name);
+  }
+
   /**
    * Checks whether a {@link VariantInstance} is either registered or created.
    */
@@ -193,19 +204,36 @@ export class VariantInstanceManager extends EventBroadcaster {
    *
    * @emits {@link Event.VARIANT_INSTANCE_CLONED}
    */
-  public async clone(name: string, newName: string, parameters?: ParameterBag): Promise<VariantInstance> {
+  public async clone(
+    name: string,
+    newName: string,
+    parameters?: ParameterBag,
+    tagMapping?: TagMapping
+  ): Promise<VariantInstance> {
     if (!this.variantInstances.has(name)) {
       throw Error(`VariantInstance with name "${name}" does not exist.`);
     }
+    if (this.viewer.tagManager.parameters.size > 0) {
+      // visible state of nodes should be updated by tag manager if it is in use
+      // this logic is programmed in the elements `addParameterObservers` function and will be triggered by setting the
+      // variants visibility to true
+      parameters = { [Parameter.VISIBLE]: true, ...(parameters ?? {}) };
+    }
     const variantInstance = this.variantInstances.get(name)!;
     const definition = {
       name: this.ensureUniqueName(newName ? newName : name),
       variant: variantInstance.variant.id,
       parameters: parameters,
     };
-    const living = await variantInstance.variant.createLiving(definition.parameters);
-    const variantInstanceClone = new VariantInstance(living, definition.name);
+    const variantInstanceClone = await VariantInstance.createLiving(
+      variantInstance.variant,
+      definition.name,
+      definition.parameters
+    );
     this.variantInstances.set(definition.name, variantInstanceClone);
+    reportDuplicateNodeNames(duplicateNodeNames(this.viewer.scene.getNodes(), n => n instanceof TransformNode));
+    this.viewer.tagManager.mapNodesAndTags(variantInstanceClone.variant.elementNodesFlat, tagMapping ?? {});
+    await this.viewer.tagManager.applyExistingParameterValuesTo(variantInstanceClone.variant.elementNodesFlat);
     variantInstance.broadcastEvent(Event.VARIANT_INSTANCE_CLONED, variantInstanceClone);
     return variantInstanceClone;
   }
@@ -242,8 +270,7 @@ export class VariantInstanceManager extends EventBroadcaster {
       throw new Error(`Viewer has not been properly bootstrapped (rootVariant missing).`);
     }
     const variant = await this.rootVariant.getDescendant(definition.variant);
-    const living = await variant.createLiving(definition.parameters);
-    const variantInstance = new VariantInstance(living, definition.name);
+    const variantInstance = await VariantInstance.createLiving(variant, definition.name, definition.parameters);
     this.variantInstances.set(definition.name, variantInstance);
     this.broadcastEvent(Event.VARIANT_INSTANCE_CREATED, variantInstance);
     return variantInstance;

package/src/api/store/specStorage.ts

@@ -18,6 +18,23 @@ export class SpecStorage {
     return (this.instance = new this(structureJson));
   }
 
+  /**
+   * Gets the {@link SpecStorage} instance.
+   */
+  public static getInstance(): SpecStorage {
+    if (!this.instance || !this.instance.spec) {
+      throw new Error(`SpecStore has not been properly created.`);
+    }
+    return this.instance;
+  }
+
+  /**
+   * Gets the spec from the {@link SpecStorage}.
+   */
+  public static getSpec(): StructureJson {
+    return this.getInstance().spec;
+  }
+
   /**
    * Destroys the current instance to allow reinstantiating the SpecStorage.
    */