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

package/src/api/manager/variantInstanceManager.ts

@@ -1,265 +1,297 @@
-import { DottedPath } from '../classes/dottedPath';
-import { Event } from '../classes/event';
-import { EventBroadcaster } from '../classes/eventBroadcaster';
-import { Parameter } from '../classes/parameter';
-import { Variant } from '../classes/variant';
-import { VariantInstance } from '../classes/variantInstance';
-import { merge } from 'lodash-es';
-
-/**
- * There's usually no need to instantiate a {@link VariantInstanceManager} yourself as it is provided by each
- * {@link Viewer} instance via its {@link Viewer.variantInstances}
- */
-export class VariantInstanceManager extends EventBroadcaster {
-  protected variantInstancePromises: Map<string, Promise<VariantInstance>> = new Map();
-
-  protected variantInstances: Map<string, VariantInstance> = new Map();
-
-  protected variantInstanceDefinitions: Map<string, VariantInstanceDefinition> = new Map();
-
-  protected parameters: ParameterBag = {};
-
-  protected queues: { [name: string]: Promise<VariantInstance>[] } = {};
-
-  /**
-   * Constructor.
-   */
-  protected constructor(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);
-  }
-
-  /**
-   * Gets all instances.
-   */
-  get all() {
-    const all: VariantInstance[] = [];
-    this.variantInstances.forEach(variantInstance => all.push(variantInstance));
-    return all;
-  }
-
-  /**
-   * Gets all instance definitions.
-   */
-  get allDefinitions() {
-    const all: VariantInstanceDefinition[] = [];
-    this.variantInstanceDefinitions.forEach(definition => all.push(definition));
-    return all;
-  }
-
-  /**
-   * Checks whether a {@link VariantInstance} is either registered or created.
-   */
-  public has(name: string) {
-    return this.variantInstances.has(name) || this.variantInstanceDefinitions.has(name);
-  }
-
-  /**
-   * Retrieves a {@link VariantInstance}.
-   * If the instance has been created, the created instance will be returned.
-   * If the instance is registered, the instance will be created and returned.
-   * if the instance has already been requested and is currently pending, the dedicated promise will be returned.
-   * If none of these apply, an Error is thrown.
-   *
-   * @emits {@link Event.VARIANT_INSTANCE_CREATED}
-   */
-  public async get(name: string): Promise<VariantInstance> {
-    // 1) see if we have an instance of that name already and return it if found
-    if (this.variantInstances.has(name)) {
-      return this.variantInstances.get(name)!; // cannot be null, hence the exclamation mark
-    }
-
-    // 2) try to get promise from list of requested instances and return it if found
-    if (this.variantInstancePromises.has(name)) {
-      return this.variantInstancePromises.get(name)!;
-    }
-
-    // 3) see if there's a definition of that name, create an instance from it and store the related promise
-    if (this.variantInstanceDefinitions.has(name)) {
-      const definition = this.variantInstanceDefinitions.get(name)!; // cannot be null
-      const vip = this.createFromDefinition(definition);
-      this.variantInstancePromises.set(name, vip);
-      // remove promise after it has been finished
-      vip.then(() => this.variantInstancePromises.delete(name));
-
-      return vip;
-    }
-
-    //* if we are here, no instance definition of that name exists. throw error.
-    throw Error(`VariantInstance with name "${name}" neither created nor configured.`);
-  }
-
-  /**
-   * Creates and registers a unique {@link VariantInstance}.
-   *
-   * @emits {@link Event.VARIANT_INSTANCE_CREATED}
-   */
-  public async create(
-    dottedPath: DottedPathArgument,
-    name?: string,
-    parameters?: ParameterBag
-  ): Promise<VariantInstance> {
-    const variant = DottedPath.create(dottedPath).path;
-    const definition = {
-      name: this.ensureUniqueName(name ? name : variant),
-      variant: variant,
-      parameters: parameters,
-    };
-    return await this.createFromDefinition(definition);
-  }
-
-  /**
-   * Registers a unique {@link VariantInstanceDefinition}.
-   *
-   * @emits {@link Event.VARIANT_INSTANCE_REGISTERED}
-   */
-  public register(instanceDefinition: VariantInstanceDefinition): VariantInstanceDefinition {
-    const name = instanceDefinition.name ? instanceDefinition.name : DottedPath.create(instanceDefinition.variant).path;
-    instanceDefinition.name = this.ensureUniqueName(name);
-    this.variantInstanceDefinitions.set(instanceDefinition.name, instanceDefinition);
-    this.broadcastEvent(Event.VARIANT_INSTANCE_REGISTERED, instanceDefinition);
-    return instanceDefinition;
-  }
-
-  /**
-   * Commits the {@link ParameterBag} to all registered and created {@link VariantInstance}s.
-   */
-  public async commitParameters(
-    parameters: ParameterBag = {},
-    onlyVisible: boolean = true
-  ): Promise<VariantInstanceManager> {
-    this.parameters = merge(this.parameters, parameters);
-    this.allDefinitions.forEach(definition => (definition.parameters = merge(definition.parameters, this.parameters)));
-    let instances = this.all;
-    if (onlyVisible) {
-      instances = this.all.filter(instance => instance.variant.visible);
-    }
-    const promises = instances.map(instance => instance.variant.commitParameters(this.parameters));
-    await Promise.all(promises);
-    return this;
-  }
-
-  /**
-   * Show one {@link VariantInstance}. If `exclusive` is set to `true` it will hide all other
-   * instances handled by this {@link VariantInstanceManager}. If the function is called synchronously,
-   * the calls end up in a queue according to the FIFO principle (the last one wins).
-   */
-  public async show(name: string, exclusive: boolean = false): Promise<VariantInstance> {
-    const promise: Promise<VariantInstance> = new Promise(async resolve => {
-      if (exclusive) {
-        this.allDefinitions
-          .filter(definition => definition.name !== name)
-          .forEach(definition => {
-            const parameters: ParameterBag = {};
-            parameters[Parameter.VISIBLE] = false;
-            definition.parameters = merge(definition.parameters, parameters);
-          });
-        await Promise.all(
-          this.all
-            .filter(_instance => _instance.name !== name)
-            .map(_instance => {
-              return _instance.variant.hide();
-            })
-        );
-      }
-      const instance = await this.get(name);
-      await instance.variant.show();
-      resolve(instance);
-    });
-    if (!this.queues['show']) {
-      this.queues['show'] = [];
-    }
-    this.queues['show'].push(promise);
-    for (let i = 0; i < this.queues['show'].length; i++) {
-      const instance = await this.queues['show'][i];
-      if (exclusive) {
-        if (i + 1 < this.queues['show'].length) {
-          await instance.variant.hide();
-        }
-      }
-    }
-    this.queues['show'] = [];
-    return promise;
-  }
-
-  /**
-   * Clones and registers a new {@link VariantInstance} with a new, unique name.
-   *
-   * @emits {@link Event.VARIANT_INSTANCE_CLONED}
-   */
-  public async clone(name: string, newName: string, parameters?: ParameterBag): Promise<VariantInstance> {
-    if (!this.variantInstances.has(name)) {
-      throw Error(`VariantInstance with name "${name}" does not exist.`);
-    }
-    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);
-    this.variantInstances.set(definition.name, variantInstanceClone);
-    variantInstance.broadcastEvent(Event.VARIANT_INSTANCE_CLONED, variantInstanceClone);
-    return variantInstanceClone;
-  }
-
-  /**
-   * Destroys the instance by removing the {@link Variant} and de-registering the instance.
-   *
-   * @emits {@link Event.VARIANT_INSTANCE_DESTROYED}
-   */
-  public destroy(name: string): VariantInstanceManager {
-    if (!this.variantInstances.has(name)) {
-      throw Error(`VariantInstance with name "${name}" does not exist.`);
-    }
-    const variantInstance = this.variantInstances.get(name)!;
-    variantInstance.variant.destroy();
-    this.variantInstances.delete(name);
-    variantInstance.broadcastEvent(Event.VARIANT_INSTANCE_DESTROYED, variantInstance);
-    return this;
-  }
-
-  /**
-   * Creates and registers a unique {@link VariantInstance} from `definition`.
-   *
-   * @emits {@link Event.VARIANT_INSTANCE_CREATED}
-   */
-  protected async createFromDefinition(definition: VariantInstanceDefinition): Promise<VariantInstance> {
-    if (!definition.name) {
-      throw new Error(`Given VariantInstanceDefinition ${definition.variant} is missing a name property.`);
-    }
-    if (this.variantInstances.has(definition.name)) {
-      throw new Error(`VariantInstance with name "${definition.name}" is already created.`);
-    }
-    if (!this.rootVariant) {
-      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);
-    this.variantInstances.set(definition.name, variantInstance);
-    this.broadcastEvent(Event.VARIANT_INSTANCE_CREATED, variantInstance);
-    return variantInstance;
-  }
-
-  /**
-   * Creates a unique instance name based on already registered instance names on the {@link VariantInstanceManager}.
-   * Appends an `_i` to the name where `i = 0` and increments as long as the name is not registered.
-   */
-  protected ensureUniqueName(name: string): string {
-    let instanceName = name;
-    let i = 1;
-    while (this.has(instanceName)) {
-      instanceName = `${name}_${i}`;
-      i++;
-    }
-    return instanceName;
-  }
-}
+import { DottedPath } from '../classes/dottedPath';
+import { Event } from '../classes/event';
+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';
+
+/**
+ * There's usually no need to instantiate a {@link VariantInstanceManager} yourself as it is provided by each
+ * {@link Viewer} instance via its {@link Viewer.variantInstances}
+ */
+export class VariantInstanceManager extends EventBroadcaster {
+  protected variantInstancePromises: Map<string, Promise<VariantInstance>> = new Map();
+
+  protected variantInstances: Map<string, VariantInstance> = new Map();
+
+  protected variantInstanceDefinitions: Map<string, VariantInstanceDefinition> = new Map();
+
+  protected parameters: ParameterBag = {};
+
+  protected queues: { [name: string]: Promise<VariantInstance>[] } = {};
+
+  /**
+   * Constructor.
+   */
+  protected constructor(public viewer: Viewer, protected rootVariant: Variant) {
+    super();
+  }
+
+  /**
+   * Creates a {@link VariantInstanceManager} based on given root Variant.
+   */
+  public static async create(viewer: Viewer): Promise<VariantInstanceManager> {
+    const rootVariant = await Variant.createRoot(SpecStorage.getSpec(), viewer);
+    return new VariantInstanceManager(viewer, rootVariant);
+  }
+
+  /**
+   * Gets all instances.
+   */
+  get all() {
+    const all: VariantInstance[] = [];
+    this.variantInstances.forEach(variantInstance => all.push(variantInstance));
+    return all;
+  }
+
+  /**
+   * Gets all instance definitions.
+   */
+  get allDefinitions() {
+    const all: VariantInstanceDefinition[] = [];
+    this.variantInstanceDefinitions.forEach(definition => all.push(definition));
+    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.
+   */
+  public has(name: string) {
+    return this.variantInstances.has(name) || this.variantInstanceDefinitions.has(name);
+  }
+
+  /**
+   * Retrieves a {@link VariantInstance}.
+   * If the instance has been created, the created instance will be returned.
+   * If the instance is registered, the instance will be created and returned.
+   * if the instance has already been requested and is currently pending, the dedicated promise will be returned.
+   * If none of these apply, an Error is thrown.
+   *
+   * @emits {@link Event.VARIANT_INSTANCE_CREATED}
+   */
+  public async get(name: string): Promise<VariantInstance> {
+    // 1) see if we have an instance of that name already and return it if found
+    if (this.variantInstances.has(name)) {
+      return this.variantInstances.get(name)!; // cannot be null, hence the exclamation mark
+    }
+
+    // 2) try to get promise from list of requested instances and return it if found
+    if (this.variantInstancePromises.has(name)) {
+      return this.variantInstancePromises.get(name)!;
+    }
+
+    // 3) see if there's a definition of that name, create an instance from it and store the related promise
+    if (this.variantInstanceDefinitions.has(name)) {
+      const definition = this.variantInstanceDefinitions.get(name)!; // cannot be null
+      const vip = this.createFromDefinition(definition);
+      this.variantInstancePromises.set(name, vip);
+      // remove promise after it has been finished
+      vip.then(() => this.variantInstancePromises.delete(name));
+
+      return vip;
+    }
+
+    //* if we are here, no instance definition of that name exists. throw error.
+    throw Error(`VariantInstance with name "${name}" neither created nor configured.`);
+  }
+
+  /**
+   * Creates and registers a unique {@link VariantInstance}.
+   *
+   * @emits {@link Event.VARIANT_INSTANCE_CREATED}
+   */
+  public async create(
+    dottedPath: DottedPathArgument,
+    name?: string,
+    parameters?: ParameterBag
+  ): Promise<VariantInstance> {
+    const variant = DottedPath.create(dottedPath).path;
+    const definition = {
+      name: this.ensureUniqueName(name ? name : variant),
+      variant: variant,
+      parameters: parameters,
+    };
+    return await this.createFromDefinition(definition);
+  }
+
+  /**
+   * Registers a unique {@link VariantInstanceDefinition}.
+   *
+   * @emits {@link Event.VARIANT_INSTANCE_REGISTERED}
+   */
+  public register(instanceDefinition: VariantInstanceDefinition): VariantInstanceDefinition {
+    const name = instanceDefinition.name ? instanceDefinition.name : DottedPath.create(instanceDefinition.variant).path;
+    instanceDefinition.name = this.ensureUniqueName(name);
+    this.variantInstanceDefinitions.set(instanceDefinition.name, instanceDefinition);
+    this.broadcastEvent(Event.VARIANT_INSTANCE_REGISTERED, instanceDefinition);
+    return instanceDefinition;
+  }
+
+  /**
+   * Commits the {@link ParameterBag} to all registered and created {@link VariantInstance}s.
+   */
+  public async commitParameters(
+    parameters: ParameterBag = {},
+    onlyVisible: boolean = true
+  ): Promise<VariantInstanceManager> {
+    this.parameters = merge(this.parameters, parameters);
+    this.allDefinitions.forEach(definition => (definition.parameters = merge(definition.parameters, this.parameters)));
+    let instances = this.all;
+    if (onlyVisible) {
+      instances = this.all.filter(instance => instance.variant.visible);
+    }
+    const promises = instances.map(instance => instance.variant.commitParameters(this.parameters));
+    await Promise.all(promises);
+    return this;
+  }
+
+  /**
+   * Show one {@link VariantInstance}. If `exclusive` is set to `true` it will hide all other
+   * instances handled by this {@link VariantInstanceManager}. If the function is called synchronously,
+   * the calls end up in a queue according to the FIFO principle (the last one wins).
+   */
+  public async show(name: string, exclusive: boolean = false): Promise<VariantInstance> {
+    const promise: Promise<VariantInstance> = new Promise(async resolve => {
+      if (exclusive) {
+        this.allDefinitions
+          .filter(definition => definition.name !== name)
+          .forEach(definition => {
+            const parameters: ParameterBag = {};
+            parameters[Parameter.VISIBLE] = false;
+            definition.parameters = merge(definition.parameters, parameters);
+          });
+        await Promise.all(
+          this.all
+            .filter(_instance => _instance.name !== name)
+            .map(_instance => {
+              return _instance.variant.hide();
+            })
+        );
+      }
+      const instance = await this.get(name);
+      await instance.variant.show();
+      resolve(instance);
+    });
+    if (!this.queues['show']) {
+      this.queues['show'] = [];
+    }
+    this.queues['show'].push(promise);
+    for (let i = 0; i < this.queues['show'].length; i++) {
+      const instance = await this.queues['show'][i];
+      if (exclusive) {
+        if (i + 1 < this.queues['show'].length) {
+          await instance.variant.hide();
+        }
+      }
+    }
+    this.queues['show'] = [];
+    return promise;
+  }
+
+  /**
+   * Clones and registers a new {@link VariantInstance} with a new, unique name.
+   *
+   * @param tagMapping Object for renaming tags on the clone, whereas the "key" is the tag name of orignal variant
+   * instance and the "value" is the new tag name that should be created from it.\
+   * Check the docs of the tag managers [renaming](https://3dviewer.docs.combeenation.com/pages/documentation/Tag-Manager.html#uniqueness-of-node-and-tag-names)
+   * chapter for further details.
+   *
+   * @emits {@link Event.VARIANT_INSTANCE_CLONED}
+   */
+  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 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;
+  }
+
+  /**
+   * Destroys the instance by removing the {@link Variant} and de-registering the instance.
+   *
+   * @emits {@link Event.VARIANT_INSTANCE_DESTROYED}
+   */
+  public destroy(name: string): VariantInstanceManager {
+    if (!this.variantInstances.has(name)) {
+      throw Error(`VariantInstance with name "${name}" does not exist.`);
+    }
+    const variantInstance = this.variantInstances.get(name)!;
+    variantInstance.variant.destroy();
+    this.variantInstances.delete(name);
+    variantInstance.broadcastEvent(Event.VARIANT_INSTANCE_DESTROYED, variantInstance);
+    return this;
+  }
+
+  /**
+   * Creates and registers a unique {@link VariantInstance} from `definition`.
+   *
+   * @emits {@link Event.VARIANT_INSTANCE_CREATED}
+   */
+  protected async createFromDefinition(definition: VariantInstanceDefinition): Promise<VariantInstance> {
+    if (!definition.name) {
+      throw new Error(`Given VariantInstanceDefinition ${definition.variant} is missing a name property.`);
+    }
+    if (this.variantInstances.has(definition.name)) {
+      throw new Error(`VariantInstance with name "${definition.name}" is already created.`);
+    }
+    if (!this.rootVariant) {
+      throw new Error(`Viewer has not been properly bootstrapped (rootVariant missing).`);
+    }
+    const variant = await this.rootVariant.getDescendant(definition.variant);
+    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;
+  }
+
+  /**
+   * Creates a unique instance name based on already registered instance names on the {@link VariantInstanceManager}.
+   * Appends an `_i` to the name where `i = 0` and increments as long as the name is not registered.
+   */
+  protected ensureUniqueName(name: string): string {
+    let instanceName = name;
+    let i = 1;
+    while (this.has(instanceName)) {
+      instanceName = `${name}_${i}`;
+      i++;
+    }
+    return instanceName;
+  }
+}