@combeenation/3d-viewer 19.2.0-beta1 → 20.0.0-alpha2

package/src/manager/parameter-manager.ts

@@ -1,10 +1,8 @@
 import {
-  AbstractMesh,
   Color3,
   IAssetContainer,
   Material,
   PBRMaterial,
-  StandardMaterial,
   Tags,
   TransformNode,
   Vector3,
@@ -12,16 +10,16 @@ import {
   ViewerError,
   ViewerErrorIds,
 } from '../index';
-import { getInternalMetadataValue, setInternalMetadataValue } from '../internal/metadata-helper';
-import { paintableParameterObserver } from '../internal/paintable-helper';
-import { getTagsAsStrArr } from '../internal/tags-helper';
+import { createPaintableParameter } from '../internal/parameter/paintable-parameter-helper';
+import { createBuiltInParameter } from '../internal/parameter/parameter-helper';
 import {
   BuiltInTextureParameter,
   BuiltInTextureParameterKeys,
   ParameterTextureChannelsKeys,
   createBuiltInTextureParameter,
-} from '../internal/texture-parameter-helper';
-import { capitalize, isNumber, isString } from 'lodash-es';
+} from '../internal/parameter/texture-parameter-helper';
+import { getTagsAsStrArr } from '../internal/tags-helper';
+import { capitalize, isArray, isNumber, isObject, isString } from 'lodash-es';
 
 /**
  * Parameters with a built in observer implementation
@@ -51,10 +49,16 @@ export const LegacyParameter = {
   Paintable: 'paintable',
 };
 
+export type ParameterName = string;
+
 export type MorphTargetParameterValue = { name: string; value: number };
+const isMorphTargetParameterValue = (value: InputParameterValue): value is MorphTargetParameterValue =>
+  isObject(value) && 'name' in value && isString(value.name) && 'value' in value && isNumber(value.value);
+const isMorphTargetsParameterValue = (value: ParameterValue): value is MorphTargetParameterValue[] =>
+  isArray(value) && value.every(mT => isMorphTargetParameterValue(mT));
 
-export type ParameterName = string;
-export type ParameterValue = string | number | boolean | Vector3 | Color3 | MorphTargetParameterValue;
+export type ParameterValue = string | number | boolean | Vector3 | Color3 | MorphTargetParameterValue[];
+export type InputParameterValue = Exclude<ParameterValue, MorphTargetParameterValue[]> | MorphTargetParameterValue;
 
 export type TagParameterSubject = { tagName: string; nodeName?: never; materialName?: never };
 export type NodeParameterSubject = { tagName?: never; nodeName: string; materialName?: never };
@@ -87,9 +91,14 @@ const isMaterialParameterSubject = (subject: ParameterSubject): subject is Mater
  */
 export type ParameterValues = (ParameterSubject & {
   parameterName: ParameterName;
-  value: ParameterValue;
+  value: InputParameterValue;
+  options?: ParameterOptions;
 })[];
 
+export type ParameterOptions = {
+  animationTimeMs?: number;
+};
+
 /**
  * Definition of callback function for parameter change
  */
@@ -105,6 +114,7 @@ export type ParameterObserverPayload = {
   materials: Material[];
   newValue: ParameterValue;
   oldValue: ParameterValue | undefined;
+  options?: ParameterOptions;
 };
 
 // internal type which holds the data of a certain parameter entry
@@ -113,9 +123,12 @@ type ParameterEntry = {
   parameterName: ParameterName;
   value: ParameterValue;
   oldValue: ParameterValue | undefined;
+  options?: ParameterOptions;
 };
 
 export class ParameterManager {
+  public static readonly PARAMETER_ANIMATION_NAME = '$parameterAnimation';
+
   /**
    * Parses and converts input to a boolean value, valid values are:
    * - true / false
@@ -230,7 +243,7 @@ export class ParameterManager {
     });
   }
 
-  public static parseMorphTarget(value: ParameterValue): MorphTargetParameterValue {
+  public static parseMorphTargets(value: ParameterValue): MorphTargetParameterValue[] {
     let objValue;
     if (isString(value)) {
       try {
@@ -245,8 +258,8 @@ export class ParameterManager {
       objValue = value;
     }
 
-    if (isString(objValue.name) && isNumber(objValue.value)) {
-      return { name: objValue.name, value: objValue.value };
+    if (isMorphTargetsParameterValue(objValue)) {
+      return objValue.map(mT => ({ name: mT.name, value: mT.value }));
     } else {
       throw new ViewerError({
         id: ViewerErrorIds.InvalidParameterValue,
@@ -271,9 +284,11 @@ export class ParameterManager {
   public async setNodeParameterValue(
     nodeName: string,
     parameterName: ParameterName,
-    value: ParameterValue
+    value: InputParameterValue,
+    options?: ParameterOptions
   ): Promise<boolean> {
-    const valueChanged = this._addParameterValue({ nodeName }, parameterName, value);
+    const internalValue = this._prepareInputValue(value);
+    const valueChanged = this._addParameterValue({ nodeName }, parameterName, internalValue, options);
     if (valueChanged) {
       await this._applyParameterValue({ nodeName }, parameterName);
     }
@@ -289,9 +304,11 @@ export class ParameterManager {
   public async setMaterialParameterValue(
     materialName: string,
     parameterName: ParameterName,
-    value: ParameterValue
+    value: InputParameterValue,
+    options?: ParameterOptions
   ): Promise<boolean> {
-    const valueChanged = this._addParameterValue({ materialName }, parameterName, value);
+    const internalValue = this._prepareInputValue(value);
+    const valueChanged = this._addParameterValue({ materialName }, parameterName, internalValue, options);
     if (valueChanged) {
       await this._applyParameterValue({ materialName }, parameterName);
     }
@@ -309,9 +326,11 @@ export class ParameterManager {
   public async setTagParameterValue(
     tagName: string,
     parameterName: ParameterName,
-    value: ParameterValue
+    value: InputParameterValue,
+    options?: ParameterOptions
   ): Promise<boolean> {
-    const valueChanged = this._addParameterValue({ tagName }, parameterName, value);
+    const internalValue = this._prepareInputValue(value);
+    const valueChanged = this._addParameterValue({ tagName }, parameterName, internalValue, options);
     if (valueChanged) {
       await this._applyParameterValue({ tagName }, parameterName);
     }
@@ -333,19 +352,30 @@ export class ParameterManager {
         : isMaterialParameterSubject(valueEntry)
         ? { materialName: valueEntry.materialName }
         : { tagName: valueEntry.tagName };
-
-      return { subject, parameterName: valueEntry.parameterName, value: valueEntry.value, oldValue: undefined };
+      const value = this._prepareInputValue(valueEntry.value);
+
+      return {
+        subject,
+        parameterName: valueEntry.parameterName,
+        value,
+        oldValue: undefined,
+        options: valueEntry.options,
+      };
     });
 
-    const changedParameterEntries = parameterEntries.filter(paramEntry =>
-      this._addParameterValue(paramEntry.subject, paramEntry.parameterName, paramEntry.value)
+    const changedParameterEntries = parameterEntries.filter(({ subject, parameterName, value, options }) =>
+      this._addParameterValue(subject, parameterName, value, options)
     );
 
     await this._applyParameterValues(changedParameterEntries);
 
     // convert back to original typing
     const changedParameterValues: ParameterValues = changedParameterEntries.map(paramEntry => {
-      return { ...paramEntry.subject, parameterName: paramEntry.parameterName, value: paramEntry.value };
+      const value = isMorphTargetsParameterValue(paramEntry.value)
+        ? // we can be sure that only one morph target was given on the input
+          paramEntry.value[0]
+        : paramEntry.value;
+      return { ...paramEntry.subject, parameterName: paramEntry.parameterName, value };
     });
 
     return changedParameterValues;
@@ -459,6 +489,52 @@ export class ParameterManager {
     await this._applyParameterValues(textureParameterEntriesToApply);
   }
 
+  /**
+   * @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 = getTagsAsStrArr(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 = getTagsAsStrArr(material);
+    const tagParamValue = tags.reduce<ParameterValue | undefined>((accValue, curTag) => {
+      const tagParamValue = this.getParameterValue({ tagName: curTag }, parameterName);
+      return accValue ?? tagParamValue;
+    }, undefined);
+
+    return tagParamValue;
+  }
+
   /**
    * Retrieves visibility state of node, considering pending parameter values and node hierarchy.\
    * `node.isEnabled()` alone is insufficient here, as visibility observers for the desired node or one of it's parents
@@ -470,7 +546,7 @@ export class ParameterManager {
     let curNode: TransformNode | null = node;
     let visibleByParameter: boolean | undefined = undefined;
     while (curNode && visibleByParameter !== false) {
-      const curNodeVisibleByParameter = this._getParameterValueOfNode(curNode, BuiltInParameter.Visible);
+      const curNodeVisibleByParameter = this.getParameterValueOfNode(curNode, BuiltInParameter.Visible);
       if (curNodeVisibleByParameter !== undefined) {
         visibleByParameter = curNodeVisibleByParameter as boolean;
       }
@@ -485,172 +561,31 @@ export class ParameterManager {
   }
 
   /**
-   * Parameter observer implementation of default parameters
+   * Converts the input parameter value type to the actual internally used parameter type.\
+   * ATM this is required for making morph target parameters of a specific node mergeable.
    */
-  protected _addBuiltInParameterObservers(): void {
-    this.setParameterObserver(BuiltInParameter.Visible, async ({ nodes, newValue }) => {
-      const visible = ParameterManager.parseBoolean(newValue);
-
-      const observerProms = nodes.map(async node => {
-        const visibleNested = this.getNestedVisibilityParameterValueOfNode(node);
-        if (visibleNested) {
-          // if a mesh gets visible by this operation we have to activate the assigned material which is stored in the
-          // internal metadata
-          // => consider child meshes as well (CB-10143)
-          const activatedNodes = [node, ...node.getChildMeshes(false)];
-          const setMaterialProms = activatedNodes.map(async an => {
-            const anVisibleNested = this.getNestedVisibilityParameterValueOfNode(an);
-            const anDeferredMaterial = getInternalMetadataValue(an, 'deferredMaterial');
-            const anMaterialParamValue = this._getParameterValueOfNode(an, BuiltInParameter.Material) as
-              | string
-              | undefined;
-            // get latest requested material, either from (new) parameter value or from deferred material
-            const anRequestedMaterial = anMaterialParamValue ?? anDeferredMaterial;
-            // material observer might have been executed before visibility observer
-            // => skip the material application in this case, as if it would be done twice
-            const anMaterialToBeSet = getInternalMetadataValue(an, 'materialToBeSet');
-            if (anVisibleNested && anRequestedMaterial && !anMaterialToBeSet) {
-              await this.viewer.materialManager.setMaterialOnMesh(
-                anRequestedMaterial,
-                // this cast is fine, as deferred material can only be set on meshes
-                an as AbstractMesh
-              );
-            }
-          });
-          await Promise.all(setMaterialProms);
-        }
-
-        // set enabled state anyway
-        node.setEnabled(visible);
-      });
-      await Promise.all(observerProms);
-    });
-    this.setParameterObserver(BuiltInParameter.Material, async ({ nodes, newValue }) => {
-      const material = ParameterManager.parseString(newValue);
-
-      const observerProms = nodes.map(async node => {
-        if (!(node instanceof AbstractMesh)) {
-          throw new ViewerError({
-            id: ViewerErrorIds.InvalidParameterSubject,
-            message: `Material can't be set, as the target node "${node.name}" is not a mesh`,
-          });
-        }
-
-        // only set material if the mesh is visible, or gets visible by the parameter update
-        const visible = this.getNestedVisibilityParameterValueOfNode(node);
-        if (visible) {
-          // visibility observer might have been executed before material observer
-          // => skip the material application in this case, as if it would be done twice
-          const anMaterialToBeSet = getInternalMetadataValue(node, 'materialToBeSet');
-          if (!anMaterialToBeSet) {
-            await this.viewer.materialManager.setMaterialOnMesh(material, node);
-          }
-        } else {
-          setInternalMetadataValue(node, 'deferredMaterial', material);
+  protected _prepareInputValue(inputValue: InputParameterValue): ParameterValue {
+    if (isMorphTargetParameterValue(inputValue)) {
+      return [inputValue];
+    } else if (isString(inputValue)) {
+      try {
+        const objValue = JSON.parse(inputValue);
+        if (isMorphTargetParameterValue(objValue)) {
+          return [objValue];
         }
-      });
-      await Promise.all(observerProms);
-    });
-    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);
+      } catch (e) {}
+    }
 
-      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 ViewerError({
-              id: ViewerErrorIds.InvalidParameterSubject,
-              message: `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 ViewerError({
-              id: ViewerErrorIds.InvalidParameterSubject,
-              message: `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 ViewerError({
-              id: ViewerErrorIds.InvalidParameterSubject,
-              message: `Setting metallic for material of instance "${materialCls}" not implemented`,
-            });
-        }
-      }
-    });
-    this.setParameterObserver(BuiltInParameter.Influence, async ({ nodes, newValue }) => {
-      const morphTargetValue = ParameterManager.parseMorphTarget(newValue);
-
-      for (const node of nodes) {
-        const target = node instanceof AbstractMesh && node.morphTargetManager?.getTargetByName(morphTargetValue.name);
-
-        if (target) {
-          target.influence = morphTargetValue.value;
-        } else {
-          throw new ViewerError({
-            id: ViewerErrorIds.InvalidParameterSubject,
-            message: `Morph target couldn't be found, node: ${node.name} / morph target: ${morphTargetValue.name}`,
-          });
-        }
-      }
-    });
-    this.setParameterObserver(LegacyParameter.Paintable, async ({ newValue, materials }) => {
-      paintableParameterObserver(newValue, materials, this.viewer.scene);
-    });
+    return inputValue;
+  }
 
-    // texture parameter use a more generic approach (`channel`.`parameter`) and are therefore coded in a dedicated file
+  /**
+   * Parameter observer implementation of default parameters
+   */
+  protected _addBuiltInParameterObservers(): void {
+    createBuiltInParameter(this, this.viewer.materialManager);
     createBuiltInTextureParameter(this, this.viewer.scene);
+    createPaintableParameter(this, this.viewer.scene);
   }
 
   /**
@@ -661,19 +596,31 @@ export class ParameterManager {
   protected _addParameterValue(
     subject: ParameterSubject,
     parameterName: ParameterName,
-    value: ParameterValue
+    value: ParameterValue,
+    options?: ParameterOptions
   ): boolean {
     const existingEntry = this._getEntry(subject, parameterName);
 
-    if (existingEntry?.value === value) {
+    let mergedValue = value;
+    if (existingEntry && isMorphTargetsParameterValue(existingEntry.value) && isMorphTargetsParameterValue(value)) {
+      // morph target values have to be merged instead of completely replaced
+      const map = new Map(existingEntry.value.map(e => [e.name, e]));
+      for (const item of value) {
+        map.set(item.name, item);
+      }
+      mergedValue = Array.from(map.values());
+    }
+
+    if (JSON.stringify(existingEntry?.value) === JSON.stringify(mergedValue)) {
       return false;
     }
 
     if (existingEntry) {
       existingEntry.oldValue = existingEntry.value;
-      existingEntry.value = value;
+      existingEntry.value = mergedValue;
+      existingEntry.options = options;
     } else {
-      this._parameterEntries.push({ subject, parameterName, value, oldValue: undefined });
+      this._parameterEntries.push({ subject, parameterName, value: mergedValue, oldValue: undefined, options });
     }
 
     return true;
@@ -730,6 +677,7 @@ export class ParameterManager {
       oldValue: parameterEntry.oldValue,
       nodes,
       materials,
+      options: parameterEntry.options,
     });
   }
 
@@ -797,46 +745,4 @@ export class ParameterManager {
 
     return entries;
   }
-
-  /**
-   * @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.
-   */
-  protected _getParameterValueOfNode(node: TransformNode, parameterName: string): ParameterValue | undefined {
-    const nodeParamValue = this.getParameterValue({ nodeName: node.name }, parameterName);
-    if (nodeParamValue !== undefined) {
-      return nodeParamValue;
-    }
-
-    const tags = getTagsAsStrArr(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}
-   */
-  protected _getParameterValueOfMaterial(material: Material, parameterName: string): ParameterValue | undefined {
-    const materialParamValue = this.getParameterValue({ materialName: material.name }, parameterName);
-    if (materialParamValue !== undefined) {
-      return materialParamValue;
-    }
-
-    const tags = getTagsAsStrArr(material);
-    const tagParamValue = tags.reduce<ParameterValue | undefined>((accValue, curTag) => {
-      const tagParamValue = this.getParameterValue({ tagName: curTag }, parameterName);
-      return accValue ?? tagParamValue;
-    }, undefined);
-
-    return tagParamValue;
-  }
 }

package/src/manager/scene-manager.ts

@@ -104,6 +104,8 @@ type SceneAsset = BaseAsset & {
  * This contains creating or loading scenes with certain settings for lighting, cameras and appearance in genereal.
  */
 export class SceneManager {
+  protected static _DEFAULT_SCENE_ASSET_ENVIRONMENT_URL =
+    'https://cbnpeuwstservice.blob.core.windows.net/viewer3d/static/studio.env';
   protected static _DEFAULT_SCENE_ASSET_NAME = '$defaultScene';
   protected static _DEFAULT_GROUND_PLANE_NAME = 'BackgroundPlane';
   protected static _DEFAULT_GROUND_SIZING_FACTOR = 5;
@@ -125,7 +127,7 @@ export class SceneManager {
 
     environment: {
       create: true,
-      url: 'https://assets.babylonjs.com/environments/environmentSpecular.env',
+      url: SceneManager._DEFAULT_SCENE_ASSET_ENVIRONMENT_URL,
       intensity: 1,
     },
   };