@combeenation/3d-viewer 19.1.0 → 20.0.0-alpha1

package/src/internal/parameter/parameter-helper.ts

@@ -0,0 +1,263 @@
+import {
+  AbstractMesh,
+  Animation,
+  AnimationGroup,
+  BuiltInParameter,
+  Color3,
+  MaterialManager,
+  PBRMaterial,
+  ParameterManager,
+  StandardMaterial,
+  Vector3,
+  ViewerError,
+  ViewerErrorIds,
+} from '../..';
+import { playAnimationGroupOnce } from '../animation-helper';
+import { getInternalMetadataValue, setInternalMetadataValue } from '../metadata-helper';
+
+type AnimatableProperties = 'albedoColor' | 'position' | 'rotation' | 'scaling' | 'influence';
+
+export function createBuiltInParameter(parameterManager: ParameterManager, materialManager: MaterialManager): void {
+  parameterManager.setParameterObserver(BuiltInParameter.Visible, async ({ nodes, newValue }) => {
+    const visible = ParameterManager.parseBoolean(newValue);
+
+    const observerProms = nodes.map(async node => {
+      const visibleNested = parameterManager.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 = parameterManager.getNestedVisibilityParameterValueOfNode(an);
+          const anDeferredMaterial = getInternalMetadataValue(an, 'deferredMaterial');
+          const anMaterialParamValue = parameterManager.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 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);
+  });
+  parameterManager.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 = parameterManager.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 materialManager.setMaterialOnMesh(material, node);
+        }
+      } else {
+        setInternalMetadataValue(node, 'deferredMaterial', material);
+      }
+    });
+    await Promise.all(observerProms);
+  });
+  parameterManager.setParameterObserver(BuiltInParameter.Position, async ({ nodes, newValue, options }) => {
+    const position = ParameterManager.parseVector(newValue);
+
+    for (const node of nodes) {
+      if (options?.animationTimeMs) {
+        _animateParameter(
+          node,
+          'position',
+          position,
+          `${BuiltInParameter.Position}.${node.name}`,
+          options.animationTimeMs
+        );
+      } else {
+        node.position = position;
+      }
+    }
+  });
+  parameterManager.setParameterObserver(BuiltInParameter.Rotation, async ({ nodes, newValue, options }) => {
+    const rotation = ParameterManager.parseRotation(newValue);
+
+    for (const node of nodes) {
+      if (options?.animationTimeMs) {
+        if (node.rotationQuaternion) {
+          // set initial rotation value, if rotation is defined via quaternion
+          // otherwise the animation would just jump to the end value, as there is no start value to interpolate
+          node.rotation = node.rotationQuaternion.toEulerAngles();
+        }
+        _animateParameter(
+          node,
+          'rotation',
+          rotation,
+          `${BuiltInParameter.Rotation}.${node.name}`,
+          options.animationTimeMs
+        );
+      } else {
+        node.rotation = rotation;
+      }
+    }
+  });
+  parameterManager.setParameterObserver(BuiltInParameter.Scaling, async ({ nodes, newValue, options }) => {
+    const scaling = ParameterManager.parseVector(newValue);
+
+    for (const node of nodes) {
+      if (options?.animationTimeMs) {
+        _animateParameter(
+          node,
+          'scaling',
+          scaling,
+          `${BuiltInParameter.Scaling}.${node.name}`,
+          options.animationTimeMs
+        );
+      } else {
+        node.scaling = scaling;
+      }
+    }
+  });
+  parameterManager.setParameterObserver(BuiltInParameter.Color, async ({ materials, newValue, options }) => {
+    const color = ParameterManager.parseColor(newValue);
+
+    for (const material of materials) {
+      const materialCls = material.getClassName();
+      switch (materialCls) {
+        case 'PBRMaterial':
+          if (options?.animationTimeMs) {
+            _animateParameter(
+              material as PBRMaterial,
+              'albedoColor',
+              color.toLinearSpace(),
+              `${BuiltInParameter.Color}.${material.id}`,
+              options.animationTimeMs
+            );
+          } else {
+            (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`,
+          });
+      }
+    }
+  });
+  parameterManager.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`,
+          });
+      }
+    }
+  });
+  parameterManager.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`,
+          });
+      }
+    }
+  });
+  parameterManager.setParameterObserver(BuiltInParameter.Influence, async ({ nodes, newValue, options }) => {
+    const morphTargetValues = ParameterManager.parseMorphTargets(newValue);
+
+    for (const morphTargetValue of morphTargetValues) {
+      for (const node of nodes) {
+        const target = node instanceof AbstractMesh && node.morphTargetManager?.getTargetByName(morphTargetValue.name);
+
+        if (target) {
+          if (options?.animationTimeMs) {
+            _animateParameter(
+              target,
+              'influence',
+              morphTargetValue.value,
+              `${BuiltInParameter.Influence}.${node.name}.${target.name}`,
+              options.animationTimeMs
+            );
+          } else {
+            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}`,
+          });
+        }
+      }
+    }
+  });
+}
+
+async function _animateParameter<T, K extends Extract<keyof T, AnimatableProperties>>(
+  target: T,
+  property: K,
+  value: T[K],
+  animationNameSuffix: string,
+  animationTimeMs: number
+): Promise<void> {
+  const framesPerSec = 100;
+  // extend if further `AnimatableProperties` with different types are added
+  const dataType =
+    value instanceof Vector3
+      ? Animation.ANIMATIONTYPE_VECTOR3
+      : value instanceof Color3
+      ? Animation.ANIMATIONTYPE_COLOR3
+      : Animation.ANIMATIONTYPE_FLOAT;
+
+  const animationGroup = new AnimationGroup(`${ParameterManager.PARAMETER_ANIMATION_NAME}.${animationNameSuffix}`);
+
+  const animation = new Animation(property, property, framesPerSec, dataType);
+  animation.setKeys([
+    { frame: 0, value: target[property] },
+    { frame: framesPerSec, value: value },
+  ]);
+  animationGroup.addTargetedAnimation(animation, target);
+
+  await playAnimationGroupOnce(animationGroup, framesPerSec, Math.max(animationTimeMs, 0));
+}

package/src/internal/{texture-parameter-helper.ts → parameter/texture-parameter-helper.ts}

@@ -1,6 +1,16 @@
-import { BaseTexture, Material, PBRMaterial, Scene, Texture, TextureManager, ViewerError, ViewerErrorIds } from '..';
-import { BuiltInParameter, ParameterManager } from '../manager/parameter-manager';
-import { embedAssets } from './svg-helper';
+import {
+  BaseTexture,
+  BuiltInParameter,
+  Material,
+  PBRMaterial,
+  ParameterManager,
+  Scene,
+  Texture,
+  TextureManager,
+  ViewerError,
+  ViewerErrorIds,
+} from '../..';
+import { embedAssets } from '../svg-helper';
 import isSvg from 'is-svg';
 
 /**

package/src/manager/camera-manager.ts

@@ -11,6 +11,7 @@ import {
   ViewerErrorIds,
   ViewerEvent,
 } from '../index';
+import { playAnimationGroupOnce } from '../internal/animation-helper';
 import { downloadFile } from '../internal/export-helper';
 import { nodeMatchesAnyCriteria } from '../internal/node-helper';
 import { createScreenshotCanvas, trimCanvas } from '../internal/screenshot-helper';
@@ -282,16 +283,7 @@ export class CameraManager {
       );
     }
 
-    // animation is created for 1 second (100 frames), adjust speed ratio according to desired movement time
-    const speedRatio = 1000 / durationMs;
-
-    return new Promise<void>(resolve => {
-      animationGroup.onAnimationGroupEndObservable.addOnce(() => {
-        animationGroup.dispose();
-        resolve();
-      });
-      animationGroup.start(false, speedRatio, 0, 100);
-    });
+    await playAnimationGroupOnce(animationGroup, framesPerSec, durationMs);
   }
 
   /**

package/src/manager/debug-manager.ts

@@ -15,6 +15,7 @@ import {
   Viewer,
   ViewerEvent,
 } from '../index';
+import { nodeHasLeftHandedScaling } from '../internal/math-helper';
 
 /**
  * Manager for debugging functionalities
@@ -39,7 +40,7 @@ export class DebugManager {
   }
 
   /**
-   * Enables the Babylon.js [Inspector](https://doc.babylonjs.com/toolsAndResources/tools/inspector).\
+   * Enables the Babylon.js [Inspector](https://doc.babylonjs.com/legacy/inspector/).\
    * Due to the additional size of the inspector, this function is only available in "development" builds!
    *
    * @returns Signalizes if inspector could be loaded
@@ -109,7 +110,12 @@ The inspector can only be used in development builds.`);
     const factor = DebugManager._getWorldCoordinatesAxesUnifyFactor();
     this._axesViewer = new AxesViewer(utilityLayerScene, size * factor);
 
+    let isLeftHanded = true;
     if (node) {
+      // required for correct rotation when calling right after creating the node (see CB-11240)
+      // force=true might not be needed, but it's safer
+      node.computeWorldMatrix(true);
+
       // get the world rotation of the mesh and extract the x, y, z axes from that
       // NOTE: `node.getDirection` can't be used because it considers the scaling as well, resulting in distorted axes
       const worldRotMatrix = new Matrix();
@@ -129,13 +135,15 @@ The inspector can only be used in development builds.`);
       if (node.absoluteScaling.z < 0) {
         zAxis.scaleInPlace(-1);
       }
-
       this._axesViewer.update(node.absolutePosition, xAxis, yAxis, zAxis);
+
+      isLeftHanded = nodeHasLeftHandedScaling(node);
     }
 
     DebugManager._prepareAxisVisual('X', this._axesViewer.xAxis);
     DebugManager._prepareAxisVisual('Y', this._axesViewer.yAxis);
     DebugManager._prepareAxisVisual('Z', this._axesViewer.zAxis);
+    DebugManager._drawLabel(isLeftHanded ? 'LH' : 'RH', -0.05, '#DD0060', this._axesViewer.xAxis, 2);
   }
 
   public hideCoordinateSystem(): void {
@@ -181,7 +189,6 @@ The inspector can only be used in development builds.`);
   protected static _prepareAxisVisual(labelText: string, axisNode: TransformNode): void {
     // fixed values used for label size and distance
     const colorScale = 2; // used to multiply the original color scale of 0.5 - result is 1
-    const labelSize = 0.05;
     const labelDistance = 0.4;
 
     // inherit the color from the arrow and adjust brightness scaling to be 1
@@ -191,8 +198,30 @@ The inspector can only be used in development builds.`);
 
     axisMaterial.emissiveColor = color;
 
+    DebugManager._drawLabel(labelText, labelDistance, color.toHexString(), axisNode);
+  }
+
+  /**
+   * More generic function for drawing a letter on a axis arrow, e.g. for drawing coordinate system letters
+   */
+  protected static _drawLabel(
+    labelText: string,
+    labelDistance: number,
+    color: string,
+    axisNode: TransformNode,
+    xScale = 1
+  ): void {
+    const labelHeight = 0.05;
+    const labelWidth = labelHeight * xScale;
+    const textureHeight = 1024;
+    const textureWidth = textureHeight * xScale;
+
     const utilityLayerScene = UtilityLayerRenderer.DefaultUtilityLayer.utilityLayerScene;
-    const labelPlane = MeshBuilder.CreatePlane(`${labelText}_label`, { size: labelSize }, utilityLayerScene);
+    const labelPlane = MeshBuilder.CreatePlane(
+      `${labelText}_label`,
+      { width: labelWidth, height: labelHeight },
+      utilityLayerScene
+    );
     labelPlane.parent = axisNode;
     labelPlane.position = new Vector3(0, 0, labelDistance);
     // keep orientation of mesh, so that it is always visible, independent of the camera position
@@ -201,12 +230,12 @@ The inspector can only be used in development builds.`);
     // create GUI element
     const textElement = new TextBlock();
     textElement.text = labelText;
-    textElement.color = color.toHexString();
+    textElement.color = color;
     textElement.fontSize = '100%';
     textElement.fontFamily = 'Arial';
     textElement.fontWeight = 'bold';
 
-    const labelTexture = AdvancedDynamicTexture.CreateForMesh(labelPlane);
+    const labelTexture = AdvancedDynamicTexture.CreateForMesh(labelPlane, textureWidth, textureHeight);
     labelTexture.addControl(textElement);
   }
 

package/src/manager/model-manager.ts

@@ -10,6 +10,7 @@ import {
 } from '../index';
 import { BaseAsset, loadAsset, prepareAssetForScene } from '../internal/asset-helper';
 import { cloneModelAssetContainer } from '../internal/cloning-helper';
+import { flipHandednessOfNode, nodeHasLeftHandedScaling } from '../internal/math-helper';
 import { isArray } from 'lodash-es';
 
 export type ParsedDecalConfiguration = DecalConfiguration & { materialId?: string; tags?: string };
@@ -24,6 +25,11 @@ export type ModelVisibilityEntry = {
   visible: boolean;
 };
 
+export type ModelData = {
+  assetContainer: AssetContainer;
+  rootNode?: TransformNode;
+};
+
 /**
  * Callback for renaming nodes when cloning nodes in a model
  */
@@ -34,6 +40,12 @@ export type NodeNamingStrategy = (node: TransformNode, newModelName: string) =>
 export type TagNamingStrategy = (tag: string, newModelName: string) => string;
 
 export type ModelCloneOptions = {
+  /**
+   * Indicates if cloned model should be shown immediately
+   *
+   * Default: true
+   */
+  show?: boolean;
   /**
    * `true:` Creates "[InstancedMeshes](https://doc.babylonjs.com/typedoc/classes/BABYLON.InstancedMesh)" from meshes of
    * the base model instead of "independent" meshes. Most of the data, especially the geometry and material assignment
@@ -42,6 +54,21 @@ export type ModelCloneOptions = {
    * clones.
    */
   createInstance?: boolean;
+  /**
+   * Optionally set a parent node for the cloned model directly.\
+   * Coordinate system handedness of the cloned model root node will be adapted to fit the handedness of this parent
+   * node.
+   * - parentNode left handed (Babylon.js default): leave imported model root node as is
+   * - parentNode right handed (e.g. when adding to existing structure): flip handedness, resetting rotation to 0/0/0
+   *   and scaling to 1/1/1
+   */
+  parentNode?: TransformNode;
+  /**
+   * Optinally overwrite name of root node.\
+   * This is especially useful for improving the readability of the node structure via the inspector.\
+   * This setting has priority over the `nodeNamingStrategy`.
+   */
+  rootNodeName?: string;
   nodeNamingStrategy?: NodeNamingStrategy;
   tagNamingStrategy?: TagNamingStrategy;
 };
@@ -252,12 +279,9 @@ export class ModelManager {
    * @param options additional options for the cloning procedure, like renaming algorithms
    * @returns asset container for further processing of the clone
    */
-  public async cloneModel(
-    name: string,
-    newModelName: string,
-    show: boolean = true,
-    options?: ModelCloneOptions
-  ): Promise<AssetContainer> {
+  public async cloneModel(name: string, newModelName: string, options?: ModelCloneOptions): Promise<ModelData> {
+    const { show, createInstance, parentNode, rootNodeName } = options ?? {};
+
     const sourceModel = this._getModel(name);
     if (!sourceModel) {
       throw new ViewerError({
@@ -286,15 +310,38 @@ export class ModelManager {
       state: 'loaded',
       assetContainer: cloneModelAssetContainer(sourceModel.assetContainer, newModelName, this.viewer.scene, options),
       isClone: true,
-      sourceModelName: options?.createInstance ? sourceModel.name : undefined,
+      sourceModelName: createInstance ? sourceModel.name : undefined,
     };
     this._modelAssets[newModelName] = clonedModel;
 
-    if (show) {
+    const rootNode = this._getRootNodeOfModel(clonedModel.assetContainer);
+    if (rootNode && rootNodeName) {
+      rootNode.name = rootNodeName;
+    }
+
+    if (show !== false) {
       await this._showModel(clonedModel);
+
+      if (parentNode && rootNode) {
+        const parentNodeIsLeftHanded = nodeHasLeftHandedScaling(parentNode);
+
+        // Freshly loaded (and cloned) models are left handed by default.
+        // If the parent node is right handed, we know that a conversion has already been done and the root node
+        // conversion node of the new model has to be reset.
+        //
+        // We expect a rotation of 0/0/0 and scaling 1/1/1 when following our default workflow, which is uploading GLBs
+        // on the platform.
+        // Still it's a generic solution and so we actually flip the current world matrix instead of applying these
+        // transformation values in a hardcoded way.
+        if (!parentNodeIsLeftHanded) {
+          flipHandednessOfNode(rootNode);
+        }
+
+        rootNode.parent = parentNode;
+      }
     }
 
-    return clonedModel.assetContainer;
+    return { assetContainer: clonedModel.assetContainer, rootNode };
   }
 
   /**
@@ -335,11 +382,11 @@ export class ModelManager {
   }
 
   /**
-   * Loads and returns the asset container of a certain model.\
+   * Loads the model and returns the asset container and root node of that model.\
    * This can be used to access the models content without having to add it to the scene.\
-   * A typical use case is to clone or instantiate a node from a "library" model.
+   * A typical use case is to clone or instantiate a model or single node from a "library" model.
    */
-  public async getAssetContainerOfModel(name: string): Promise<AssetContainer> {
+  public async getModelData(name: string): Promise<ModelData> {
     const model = this._getModel(name);
     if (!model) {
       throw new ViewerError({
@@ -358,7 +405,9 @@ export class ModelManager {
       await this._prepareModelForScene(model);
     }
 
-    return model.assetContainer;
+    const rootNode = this._getRootNodeOfModel(model.assetContainer);
+
+    return { assetContainer: model.assetContainer, rootNode };
   }
 
   /**
@@ -465,4 +514,23 @@ export class ModelManager {
     model.assetContainer.removeFromScene();
     model.state = 'loaded';
   }
+
+  /**
+   * Returns the root node of a models asset container.\
+   * This can be useful to reposition an entire (cloned) model.\
+   * Function expects only one root `TransformNode` and will return `undefined` otherwise.
+   */
+  protected _getRootNodeOfModel(assetContainer: AssetContainer): TransformNode | undefined {
+    // `assetContainer.rootNodes` can also contain other `Node` types like lights or cameras, which we don't want here
+    const rootNodes = assetContainer.rootNodes.filter(node => node instanceof TransformNode) as TransformNode[];
+    if (rootNodes.length === 0) {
+      console.warn(`No root node found for associated model`);
+      return undefined;
+    } else if (rootNodes.length > 1) {
+      console.warn(`Mutltiple root nodes found for associated model`);
+      return undefined;
+    } else {
+      return rootNodes[0];
+    }
+  }
 }