@combeenation/3d-viewer 12.4.1 → 13.0.0

package/src/manager/parameterManager.ts

@@ -0,0 +1,652 @@
+import {
+  AbstractMesh,
+  AbstractScene,
+  Color3,
+  Material,
+  PBRMaterial,
+  StandardMaterial,
+  TransformNode,
+  Vector3,
+  Viewer,
+  ViewerError,
+  ViewerErrorIds,
+} from '../index';
+import { getInternalMetadataValue, setInternalMetadataValue } from '../internal/metadataHelper';
+import { paintableParameterObserver } from '../internal/paintableHelper';
+import { getTags, hasTag } from '../internal/tagsHelper';
+import { capitalize, isString } from 'lodash-es';
+
+/**
+ * Parameters with a built in observer implementation
+ */
+export const BuiltInParameter = {
+  Visible: 'visible',
+  Material: 'material',
+  Position: 'position',
+  Rotation: 'rotation',
+  Scaling: 'scaling',
+  Color: 'color',
+  Roughness: 'roughness',
+  Metallic: 'metallic',
+  Paintable: 'paintable',
+};
+
+export type ParameterName = string;
+export type ParameterValue = string | number | boolean;
+
+export type TagParameterSubject = { tagName: string; nodeName?: never; materialName?: never };
+export type NodeParameterSubject = { tagName?: never; nodeName: string; materialName?: never };
+export type MaterialParameterSubject = { tagName?: never; nodeName?: never; materialName: string };
+
+/**
+ * Defines which objects are affected by the parameter.\
+ * This can be single nodes and materials or tags, which can be used to apply a parameter to a group of nodes or
+ * materials.
+ */
+export type ParameterSubject = TagParameterSubject | NodeParameterSubject | MaterialParameterSubject;
+
+const isTagParameterSubject = (subject: ParameterSubject): subject is TagParameterSubject =>
+  'tagName' in subject && !!subject.tagName;
+const isNodeParameterSubject = (subject: ParameterSubject): subject is NodeParameterSubject =>
+  'nodeName' in subject && !!subject.nodeName;
+const isMaterialParameterSubject = (subject: ParameterSubject): subject is MaterialParameterSubject =>
+  'materialName' in subject && !!subject.materialName;
+
+/**
+ * Bulk of targeted parameter values, mainly used as input for {@link ParameterManager.setParameterValues} function.\
+ * E.g.
+ * ```
+ * [
+ *  { nodeName: 'someMesh', parameterName: BuiltInParameter.Visible, value: false },
+ *  { materialName: 'someMaterial', parameterName: BuiltInParameter.Color, value: '#DD0060' }
+ * ]
+ * ```
+ * Each parameter value entry has to set exactly one of the subject keys (`nodeName`, `materialName` or `tagName`)
+ */
+export type ParameterValues = (ParameterSubject & {
+  parameterName: ParameterName;
+  value: ParameterValue;
+})[];
+
+/**
+ * Definition of callback function for parameter change
+ */
+export type ParameterObserver = (payload: ParameterObserverPayload) => Promise<void>;
+
+/**
+ * Payload of parameter observer.\
+ * Contains current data of parameter entry, which can be usefull for implementing the dedicated observer
+ */
+export type ParameterObserverPayload = {
+  subject: ParameterSubject;
+  nodes: TransformNode[];
+  materials: Material[];
+  newValue: ParameterValue;
+  oldValue: ParameterValue | undefined;
+};
+
+// internal type which holds the data of a certain parameter entry
+type ParameterEntry = {
+  subject: ParameterSubject;
+  parameterName: ParameterName;
+  value: ParameterValue;
+  oldValue: ParameterValue | undefined;
+};
+
+export class ParameterManager {
+  /**
+   * Parses and converts input to a boolean value, valid values are:
+   * - true / false
+   * - 1 / 0
+   */
+  public static parseBoolean(value: ParameterValue): boolean {
+    if (value.toString() === 'true' || value.toString() === '1') {
+      return true;
+    } else if (value.toString() === 'false' || value.toString() === '0') {
+      return false;
+    }
+    throw new ViewerError({
+      id: ViewerErrorIds.InvalidParameterValue,
+      message: `Unable to parse "${value}" to a boolean`,
+    });
+  }
+
+  /**
+   * Parses and converts input to a number value
+   */
+  public static parseNumber(value: ParameterValue): number {
+    return parseFloat(value.toString());
+  }
+
+  /**
+   * Parses and converts input to a string value
+   */
+  public static parseString(value: ParameterValue): string {
+    return value.toString();
+  }
+
+  // TODO WTT: enable setting Vector3 on the input directly
+  /**
+   * Parses a string of format "(x,y,z)"" to a "Vector3".
+   */
+  public static parseVector(value: ParameterValue): Vector3 {
+    if (!isString(value)) {
+      throw new ViewerError({
+        id: ViewerErrorIds.InvalidParameterValue,
+        message: `Unable to parse "${value}" to a vector: not a string`,
+      });
+    }
+    let cleanedValue = value.split(' ').join('');
+    if (cleanedValue.startsWith('(') && cleanedValue.endsWith(')')) {
+      cleanedValue = cleanedValue.substring(1, cleanedValue.length - 1);
+      const [x, y, z] = cleanedValue.split(',').map(value => parseFloat(value));
+      return new Vector3(x, y, z);
+    } else {
+      throw new ViewerError({
+        id: ViewerErrorIds.InvalidParameterValue,
+        message: `Unable to parse "${value}" to a vector: expected "(x,y,z)"`,
+      });
+    }
+  }
+
+  // TODO WTT: enable setting Vector3 on the input directly (maybe quaternion as well)
+  /**
+   * Parses a string of format `'(x,y,z)'` with angular degrees to a `Vector3` with rotation information in radians.
+   */
+  public static parseRotation(value: ParameterValue): Vector3 {
+    const rotation = ParameterManager.parseVector(value);
+    const deg2rad = (deg: number): number => {
+      return (deg * Math.PI) / 180;
+    };
+    return rotation.set(deg2rad(rotation.x), deg2rad(rotation.y), deg2rad(rotation.z));
+  }
+
+  // TODO WTT: enable setting Color3 on the input directly
+  /**
+   * Parses a string of format `'#rrggbb'` or `'(r,g,b)'` to a `Color3`.
+   */
+  public static parseColor(value: ParameterValue): Color3 {
+    const cleanedValue = value.toString().split(' ').join('');
+    if (cleanedValue.startsWith('#')) {
+      return Color3.FromHexString(value.toString());
+    }
+    if (cleanedValue.startsWith('(') && cleanedValue.endsWith(')')) {
+      const rgb = cleanedValue.substring(1, cleanedValue.length - 1);
+      const [r, g, b] = rgb.split(',').map(value => parseFloat(value));
+      return Color3.FromInts(r, g, b);
+    }
+    const humanReadable = capitalize(cleanedValue);
+
+    if (Object.prototype.hasOwnProperty.call(Color3, humanReadable)) {
+      return (Color3 as any)[humanReadable]();
+    }
+    throw new ViewerError({
+      id: ViewerErrorIds.InvalidParameterValue,
+      message: `Unable to parse "${value}" to a color: expected "#rrggbb", "(r,g,b)" or any human readable (e.g. Red) property implemented in Color3`,
+    });
+  }
+
+  protected _parameterEntries: ParameterEntry[] = [];
+  protected _parameterObserver: { [parameterName: ParameterName]: ParameterObserver } = {};
+
+  public constructor(protected viewer: Viewer) {
+    this._addBuiltInParameterObservers();
+  }
+
+  /**
+   * Set parameter value for a certain node and calls the corresponding observer if the value has changed
+   *
+   * @returns "true" if parameter value has changed
+   */
+  public async setNodeParameterValue(
+    nodeName: string,
+    parameterName: ParameterName,
+    value: ParameterValue
+  ): Promise<boolean> {
+    const valueChanged = this._addParameterValue({ nodeName }, parameterName, value);
+    if (valueChanged) {
+      await this._applyParameterValue({ nodeName }, parameterName);
+    }
+
+    return valueChanged;
+  }
+
+  /**
+   * Set parameter value for a certain material and calls the corresponding observer if the value has changed
+   *
+   * @returns "true" if parameter value has changed
+   */
+  public async setMaterialParameterValue(
+    materialName: string,
+    parameterName: ParameterName,
+    value: ParameterValue
+  ): Promise<boolean> {
+    const valueChanged = this._addParameterValue({ materialName }, parameterName, value);
+    if (valueChanged) {
+      await this._applyParameterValue({ materialName }, parameterName);
+    }
+
+    return valueChanged;
+  }
+
+  /**
+   * Set parameter value for a certain tag and calls the corresponding observer if the value has changed.\
+   * Setting a parameter value on a tag can affect multiple nodes and tags, depending which of these objects contains
+   * the desired tag.
+   *
+   * @returns "true" if parameter value has changed
+   */
+  public async setTagParameterValue(
+    tagName: string,
+    parameterName: ParameterName,
+    value: ParameterValue
+  ): Promise<boolean> {
+    const valueChanged = this._addParameterValue({ tagName }, parameterName, value);
+    if (valueChanged) {
+      await this._applyParameterValue({ tagName }, parameterName);
+    }
+
+    return valueChanged;
+  }
+
+  /**
+   * Set multiple parameter values simultaniously.\
+   * Tag parameters are applied before node and material parameters, node and materials are more specific and should
+   * have priority.
+   *
+   * @returns Array of parameters, which have changed values
+   */
+  public async setParameterValues(values: ParameterValues): Promise<ParameterValues> {
+    const parameterEntries = values.map<ParameterEntry>(valueEntry => {
+      const subject: ParameterSubject = isNodeParameterSubject(valueEntry)
+        ? { nodeName: valueEntry.nodeName }
+        : isMaterialParameterSubject(valueEntry)
+        ? { materialName: valueEntry.materialName }
+        : { tagName: valueEntry.tagName };
+
+      return { subject, parameterName: valueEntry.parameterName, value: valueEntry.value, oldValue: undefined };
+    });
+
+    const changedParameterEntries = parameterEntries.filter(paramEntry =>
+      this._addParameterValue(paramEntry.subject, paramEntry.parameterName, paramEntry.value)
+    );
+
+    await this._applyParameterValues(changedParameterEntries);
+
+    // convert back to original typing
+    const changedParameterValues: ParameterValues = changedParameterEntries.map(paramEntry => {
+      return { ...paramEntry.subject, parameterName: paramEntry.parameterName, value: paramEntry.value };
+    });
+
+    return changedParameterValues;
+  }
+
+  /**
+   * @returns desired parameter value or "undefined" if parameter entry is not available.
+   */
+  public getParameterValue(subject: ParameterSubject, parameterName: ParameterName): ParameterValue | undefined {
+    const entry = this._getEntry(subject, parameterName);
+
+    return entry?.value;
+  }
+
+  /**
+   * Define observer callback for certain parameter.\
+   * There can only be one observer for a certain parameter name.\
+   * Parameter observers can not be overwritten once they are defined, this also includes system observers for
+   * {@link BuiltInParameter}.
+   */
+  public setParameterObserver(parameterName: ParameterName, observer: ParameterObserver): void {
+    if (this._parameterObserver[parameterName]) {
+      console.warn(`Observer for parameter "${parameterName}" already set`);
+      return;
+    }
+
+    this._parameterObserver[parameterName] = observer;
+  }
+
+  /**
+   * Print all parameter entries in table format into the console
+   */
+  public printAllParameters(): void {
+    const printable = this._parameterEntries.map(entry => ({
+      ...entry,
+      subject: JSON.stringify(entry.subject),
+    }));
+
+    console.table(printable);
+  }
+
+  /**
+   * Applies all existing parameter entries to a certain "model", as defined in the {@link ModelManager}.\
+   * This can be usefull when updating the model before showing it in the scene.
+   *
+   * @internal
+   */
+  public async applyAllParameterValuesToModel(model: AbstractScene): Promise<void> {
+    const parameterEntriesToApply = this._parameterEntries;
+
+    await this._applyParameterValues(parameterEntriesToApply, model);
+  }
+
+  /**
+   * Applies all parameter values which are targeting a material.\
+   * This can be usefull when updating a material definition before creating it.
+   *
+   * @internal
+   */
+  public async applyParameterValuesToMaterial(material: Material): Promise<void> {
+    const tags = getTags(material);
+
+    const parameterEntriesToApply: ParameterEntry[] = [];
+    tags.forEach(tagName => {
+      const tagParamEntries = this._getEntriesOfSubject({ tagName });
+      parameterEntriesToApply.push(...tagParamEntries);
+    });
+
+    const materialParamEntries = this._getEntriesOfSubject({ materialName: material.id });
+    parameterEntriesToApply.push(...materialParamEntries);
+
+    await this._applyParameterValues(parameterEntriesToApply);
+  }
+
+  /**
+   * @returns Desired parameter value of a certain node.
+   * Tags are considered as well but have lower priority than node parameters, as these are more specific.
+   *
+   * @internal
+   */
+  public getParameterValueOfNode(node: TransformNode, parameterName: string): ParameterValue | undefined {
+    const nodeParamValue = this.getParameterValue({ nodeName: node.name }, parameterName);
+    if (nodeParamValue !== undefined) {
+      return nodeParamValue;
+    }
+
+    const tags = getTags(node);
+    const tagParamValue = tags.reduce<ParameterValue | undefined>((accValue, curTag) => {
+      // NOTE: it is possible that values are available for multiple tags
+      // in this case the resulting parameter value is quite "random" as the last tag in the tag string of the node has
+      // priority
+      const tagParamValue = this.getParameterValue({ tagName: curTag }, parameterName);
+      return accValue ?? tagParamValue;
+    }, undefined);
+
+    return tagParamValue;
+  }
+
+  /**
+   * @returns Desired parameter value of a certain material.
+   * Tags are considered as well but have lower priority than material parameters, as these are more specific.
+   * Unused ATM, but added for consistency as counter part for {@link getParameterValueOfNode}
+   *
+   * @internal
+   */
+  public getParameterValueOfMaterial(material: Material, parameterName: string): ParameterValue | undefined {
+    const materialParamValue = this.getParameterValue({ materialName: material.name }, parameterName);
+    if (materialParamValue !== undefined) {
+      return materialParamValue;
+    }
+
+    const tags = getTags(material);
+    const tagParamValue = tags.reduce<ParameterValue | undefined>((accValue, curTag) => {
+      const tagParamValue = this.getParameterValue({ tagName: curTag }, parameterName);
+      return accValue ?? tagParamValue;
+    }, undefined);
+
+    return tagParamValue;
+  }
+
+  /**
+   * Parameter observer implementation of default parameters
+   */
+  protected _addBuiltInParameterObservers(): void {
+    this.setParameterObserver(BuiltInParameter.Visible, async ({ nodes, newValue }) => {
+      const visible = ParameterManager.parseBoolean(newValue);
+
+      for (const node of nodes) {
+        if (visible) {
+          const deferredMaterial = getInternalMetadataValue(node, 'deferredMaterial');
+          if (deferredMaterial) {
+            await this.viewer.materialManager.setMaterialOnMesh(deferredMaterial as string, node as AbstractMesh);
+          }
+
+          node.setEnabled(true);
+        } else {
+          node.setEnabled(false);
+        }
+      }
+    });
+    this.setParameterObserver(BuiltInParameter.Material, async ({ nodes, newValue }) => {
+      const material = ParameterManager.parseString(newValue);
+
+      for (const node of nodes) {
+        // NOTE: don't use node.isEnabled() as visibility observer is probably called in same cycle but later
+        // however the parameter value is already correct at this stage
+        const rawVisibleValue = this.getParameterValueOfNode(node, BuiltInParameter.Visible);
+        const visible =
+          rawVisibleValue !== undefined ? ParameterManager.parseBoolean(rawVisibleValue) : node.isEnabled();
+        if (visible) {
+          // TODO WTT: check mesh type and throw error if it doesn't fit
+          // think of creating a framework with type guards (isMesh, canHaveMaterial, ...) around this
+          await this.viewer.materialManager.setMaterialOnMesh(material, node as AbstractMesh);
+        } else {
+          setInternalMetadataValue(node, 'deferredMaterial', material);
+        }
+      }
+    });
+    this.setParameterObserver(BuiltInParameter.Position, async ({ nodes, newValue }) => {
+      const position = ParameterManager.parseVector(newValue);
+
+      for (const node of nodes) {
+        node.position = position;
+      }
+    });
+    this.setParameterObserver(BuiltInParameter.Rotation, async ({ nodes, newValue }) => {
+      const rotation = ParameterManager.parseRotation(newValue);
+
+      for (const node of nodes) {
+        node.rotation = rotation;
+      }
+    });
+    this.setParameterObserver(BuiltInParameter.Scaling, async ({ nodes, newValue }) => {
+      const scaling = ParameterManager.parseVector(newValue);
+
+      for (const node of nodes) {
+        node.scaling = scaling;
+      }
+    });
+    this.setParameterObserver(BuiltInParameter.Color, async ({ materials, newValue }) => {
+      const color = ParameterManager.parseColor(newValue);
+
+      for (const material of materials) {
+        const materialCls = material.getClassName();
+        switch (materialCls) {
+          case 'PBRMaterial':
+            (material as PBRMaterial).albedoColor = color.toLinearSpace();
+            break;
+          case 'StandardMaterial':
+            (material as StandardMaterial).diffuseColor = color;
+            break;
+          default:
+            throw new Error(`Setting color for material of instance "${materialCls}" not implemented`);
+        }
+      }
+    });
+    this.setParameterObserver(BuiltInParameter.Roughness, async ({ materials, newValue }) => {
+      const roughness = ParameterManager.parseNumber(newValue);
+
+      for (const material of materials) {
+        const materialCls = material.getClassName();
+        switch (materialCls) {
+          case 'PBRMaterial':
+            (material as PBRMaterial).roughness = roughness;
+            break;
+          case 'StandardMaterial':
+            (material as StandardMaterial).roughness = roughness;
+            break;
+          default:
+            throw new Error(`Setting rougness for material of instance "${materialCls}" not implemented`);
+        }
+      }
+    });
+    this.setParameterObserver(BuiltInParameter.Metallic, async ({ materials, newValue }) => {
+      const metallic = ParameterManager.parseNumber(newValue);
+
+      for (const material of materials) {
+        const materialCls = material.getClassName();
+        switch (materialCls) {
+          case 'PBRMaterial':
+            (material as PBRMaterial).metallic = metallic;
+            break;
+          default:
+            throw new Error(`Setting metallic for material of instance "${materialCls}" not implemented`);
+        }
+      }
+    });
+    this.setParameterObserver(BuiltInParameter.Paintable, async ({ newValue, materials }) => {
+      paintableParameterObserver(newValue, materials, this.viewer.scene);
+    });
+  }
+
+  /**
+   * Change parameter value in array of existing parameter entries or create a new entry
+   *
+   * @returns "true" if parameter has changed or wasn't available before
+   */
+  protected _addParameterValue(
+    subject: ParameterSubject,
+    parameterName: ParameterName,
+    value: ParameterValue
+  ): boolean {
+    const existingEntry = this._getEntry(subject, parameterName);
+
+    if (existingEntry?.value === value) {
+      return false;
+    }
+
+    if (existingEntry) {
+      existingEntry.oldValue = existingEntry.value;
+      existingEntry.value = value;
+    } else {
+      this._parameterEntries.push({ subject, parameterName, value, oldValue: undefined });
+    }
+
+    return true;
+  }
+
+  /**
+   * Call parameter observer of desired parameter which usually apply the new values to the scene.
+   *
+   * @param assetContainer Asset container in which to look for the paramter entries subjects (e.g. the nodes and
+   *                       materials to which the parameter values should be applied to).\
+   *                       Defaults to `viewer.scene`.
+   */
+  protected async _applyParameterValues(
+    parameterEntries: ParameterEntry[],
+    assetContainer?: AbstractScene
+  ): Promise<void> {
+    const tagParamEntries = parameterEntries.filter(entry => isTagParameterSubject(entry.subject));
+    const nonTagParamEntries = parameterEntries.filter(entry => !isTagParameterSubject(entry.subject));
+
+    for (const entry of tagParamEntries) {
+      await this._applyParameterValue(entry.subject, entry.parameterName, assetContainer);
+    }
+    for (const entry of nonTagParamEntries) {
+      await this._applyParameterValue(entry.subject, entry.parameterName, assetContainer);
+    }
+  }
+
+  /**
+   * Call parameter observer of desired parameter
+   *
+   * @param assetContainer Optionally add an "asset container", which actually represents a model in the
+   * {@link ModelManager}. Viewer scene is used if left empty.
+   */
+  protected async _applyParameterValue(
+    subject: ParameterSubject,
+    parameterName: ParameterName,
+    assetContainer?: AbstractScene
+  ): Promise<void> {
+    const parameterEntry = this._getEntry(subject, parameterName);
+    const observer = this._parameterObserver[parameterName];
+    if (!parameterEntry || !observer) {
+      return;
+    }
+
+    const nodes = this._getAffectedNodes(subject, assetContainer);
+    const materials = this._getAffectedMaterials(subject, assetContainer);
+
+    await observer({
+      subject,
+      newValue: parameterEntry.value,
+      oldValue: parameterEntry.oldValue,
+      nodes,
+      materials,
+    });
+  }
+
+  protected _getAffectedMaterials(subject: ParameterSubject, assetContainer?: AbstractScene): Material[] {
+    assetContainer = assetContainer ?? this.viewer.scene;
+    let materials: Material[] = [];
+
+    // materials have priority over tags
+    if (isMaterialParameterSubject(subject)) {
+      materials = assetContainer.materials.filter(material => material.name === subject.materialName);
+      if (materials.length > 1) {
+        console.warn(`Multiple materials for material name "${subject.materialName}" have been found`);
+      }
+    } else if (isTagParameterSubject(subject)) {
+      materials = assetContainer.materials.filter(material => hasTag(material, subject.tagName));
+    }
+
+    return materials;
+  }
+
+  protected _getAffectedNodes(subject: ParameterSubject, assetContainer?: AbstractScene): TransformNode[] {
+    assetContainer = assetContainer ?? this.viewer.scene;
+    const allNodes = [...assetContainer.meshes, ...assetContainer.transformNodes];
+    let nodes: TransformNode[] = [];
+
+    // nodes have priority over tags
+    if (isNodeParameterSubject(subject)) {
+      nodes = allNodes.filter(node => node.name === subject.nodeName);
+      if (nodes.length > 1) {
+        console.warn(`Multiple nodes for node name "${subject.nodeName}" have been found`);
+      }
+    } else if (isTagParameterSubject(subject)) {
+      nodes = allNodes.filter(node => hasTag(node, subject.tagName));
+    }
+
+    return nodes;
+  }
+
+  protected _getEntry(subject: ParameterSubject, parameterName: ParameterName): ParameterEntry | undefined {
+    const entriesOfSubject = this._getEntriesOfSubject(subject);
+    const entry = entriesOfSubject.find(entry => entry.parameterName === parameterName);
+
+    return entry;
+  }
+
+  protected _getEntriesOfSubject(subject: ParameterSubject): ParameterEntry[] {
+    const entries = this._parameterEntries.filter(entry => {
+      const nodeNameMatches =
+        isNodeParameterSubject(entry.subject) &&
+        isNodeParameterSubject(subject) &&
+        entry.subject.nodeName === subject.nodeName;
+
+      const materialNameMatches =
+        isMaterialParameterSubject(entry.subject) &&
+        isMaterialParameterSubject(subject) &&
+        entry.subject.materialName === subject.materialName;
+
+      const tagNameMatches =
+        isTagParameterSubject(entry.subject) &&
+        isTagParameterSubject(subject) &&
+        entry.subject.tagName === subject.tagName;
+
+      return nodeNameMatches || materialNameMatches || tagNameMatches;
+    });
+
+    return entries;
+  }
+}