@combeenation/3d-viewer 0.0.1-types

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.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 = 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/textureLoadManager.ts

@@ -0,0 +1,95 @@
+import { Event } from '../classes/event';
+import { EventBroadcaster } from '../classes/eventBroadcaster';
+import { isTextureWithOnLoadObservable } from '../util/babylonHelper';
+import { sleep } from '../util/resourceHelper';
+import { BaseTexture } from '@babylonjs/core/Materials/Textures/baseTexture';
+import { Scene as BabylonScene } from '@babylonjs/core/scene';
+
+/**
+ * Keeps track of all texture loading/ready states and fires {@link Event.TEXTURE_LOADING_START} and
+ * {@link Event.TEXTURE_LOADING_END} events.
+ */
+export class TextureLoadManager extends EventBroadcaster {
+  // We're keeping track of all "loading textures" in this map ourselves instead of relying on information from
+  // `scene.textures` as that proved to be rather unreliable for our use cases.
+  // E.g. see this forums post for some more information:
+  // https://forum.babylonjs.com/t/using-scene-createdefaultenvironment-removes-textures-from-scene/35267
+  private readonly _loadingTextures: Map<number, BaseTexture> = new Map();
+
+  // Whenever we fire the {@link Event.TEXTURE_LOADING_START} event, we're starting a polling service which checks all
+  // x ms if all awaited textures are in "ready state" or not.
+  // This is basically just an additional safety net in addition to our `onLoadObservable`s and was added to prevent
+  // situations where a {@link Event.TEXTURE_LOADING_START} event is fired without an accompanying
+  // {@link Event.TEXTURE_LOADING_END} as that is a situation which can lead to load masks being endlessly shown in a
+  // cfgr.
+  // In theory this shouldn't be necessary, but we've already discovered some quirks and inconsistent behavior around
+  // the texture load observables etc. and I felt more save with this safety net in place.
+  private _readyStatePollingIntervalMs = 200;
+  private _readyStatePollingId = 0;
+
+  private constructor(public scene: BabylonScene) {
+    super();
+    this.scene.onNewTextureAddedObservable.add(texture => this.onTextureAdded(texture));
+  }
+
+  public static create(scene: BabylonScene): TextureLoadManager {
+    const loadMgr = new TextureLoadManager(scene);
+    return loadMgr;
+  }
+
+  private startReadyStatePollingIfNeeded() {
+    if (!this._readyStatePollingId) {
+      this._readyStatePollingId = window.setInterval(
+        () => this.checkLoadingTexturesState(),
+        this._readyStatePollingIntervalMs
+      );
+    }
+  }
+
+  private endReadyStatePollingIfNeeded() {
+    if (this._readyStatePollingId) {
+      window.clearInterval(this._readyStatePollingId);
+      this._readyStatePollingId = 0;
+    }
+  }
+
+  /**
+   * Checks the "ready state" of all textures inside the `this._loadingTextures` map, removes the ready ones and fires
+   * the {@link Event.TEXTURE_LOADING_END} event if no more textures are loading (i.e. "all ready").
+   */
+  private checkLoadingTexturesState() {
+    const allTexturesReadyBefore = !this._loadingTextures.size;
+    if (allTexturesReadyBefore) return;
+
+    // Remove textures which are in "ready state" from the map
+    for (const [id, texture] of this._loadingTextures) {
+      if (texture.isReady()) this._loadingTextures.delete(id);
+    }
+
+    const allTexturesReadyAfter = !this._loadingTextures.size;
+    if (allTexturesReadyAfter) {
+      this.broadcastEvent(Event.TEXTURE_LOADING_END);
+      this.endReadyStatePollingIfNeeded();
+    }
+  }
+
+  private async onTextureAdded(texture: BaseTexture) {
+    // Workaround:
+    // The texture object is not fully created when the "added observable" is called. E.g. the function
+    // `onLoadObservable` is not there at that point.
+    // More details: https://forum.babylonjs.com/t/basetexture-whenallready-returns-too-early/34501/4
+    await sleep(0);
+
+    // Some textures are already in "ready state" after the sleep -> We don't care for them anymore as well as for
+    // textures which don't come with an `onLoadObservable` (i.e. not of class {@link Texture}).
+    if (texture.isReady() || !isTextureWithOnLoadObservable(texture)) return;
+
+    const noCurrentLoadingTextures = !this._loadingTextures.size;
+    if (noCurrentLoadingTextures) {
+      this.broadcastEvent(Event.TEXTURE_LOADING_START);
+      this.startReadyStatePollingIfNeeded();
+    }
+    this._loadingTextures.set(texture.uniqueId, texture);
+    texture.onLoadObservable.addOnce(texture => this.checkLoadingTexturesState());
+  }
+}