@combeenation/3d-viewer 21.0.1-beta1 → 21.1.0-beta1

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

@@ -1,23 +1,17 @@
 import {
   AbstractMesh,
-  Animation,
-  AnimationGroup,
   BuiltInParameter,
-  Color3,
-  MaterialManager,
   PBRMaterial,
   ParameterManager,
   StandardMaterial,
-  Vector3,
+  Viewer,
   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 {
+export function createBuiltInParameter(viewer: Viewer): void {
+  const parameterManager = viewer.parameterManager;
   parameterManager.setParameterObserver(BuiltInParameter.Visible, async ({ nodes, newValue }) => {
     const visible = ParameterManager.parseBoolean(newValue);
 
@@ -40,7 +34,7 @@ export function createBuiltInParameter(parameterManager: ParameterManager, mater
           // => 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(
+            await viewer.materialManager.setMaterialOnMesh(
               anRequestedMaterial,
               // this cast is fine, as deferred material can only be set on meshes
               an as AbstractMesh
@@ -73,7 +67,7 @@ export function createBuiltInParameter(parameterManager: ParameterManager, mater
         // => 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);
+          await viewer.materialManager.setMaterialOnMesh(material, node);
         }
       } else {
         setInternalMetadataValue(node, 'deferredMaterial', material);
@@ -86,11 +80,11 @@ export function createBuiltInParameter(parameterManager: ParameterManager, mater
 
     for (const node of nodes) {
       if (options?.animationTimeMs) {
-        _animateParameter(
+        await viewer.utils.animateProperty(
           node,
           'position',
           position,
-          `${BuiltInParameter.Position}.${node.name}`,
+          `${ParameterManager.PARAMETER_ANIMATION_NAME}.${BuiltInParameter.Position}.${node.name}`,
           options.animationTimeMs
         );
       } else {
@@ -108,11 +102,11 @@ export function createBuiltInParameter(parameterManager: ParameterManager, mater
           // otherwise the animation would just jump to the end value, as there is no start value to interpolate
           node.rotation = node.rotationQuaternion.toEulerAngles();
         }
-        _animateParameter(
+        await viewer.utils.animateProperty(
           node,
           'rotation',
           rotation,
-          `${BuiltInParameter.Rotation}.${node.name}`,
+          `${ParameterManager.PARAMETER_ANIMATION_NAME}.${BuiltInParameter.Rotation}.${node.name}`,
           options.animationTimeMs
         );
       } else {
@@ -125,11 +119,11 @@ export function createBuiltInParameter(parameterManager: ParameterManager, mater
 
     for (const node of nodes) {
       if (options?.animationTimeMs) {
-        _animateParameter(
+        await viewer.utils.animateProperty(
           node,
           'scaling',
           scaling,
-          `${BuiltInParameter.Scaling}.${node.name}`,
+          `${ParameterManager.PARAMETER_ANIMATION_NAME}.${BuiltInParameter.Scaling}.${node.name}`,
           options.animationTimeMs
         );
       } else {
@@ -145,11 +139,11 @@ export function createBuiltInParameter(parameterManager: ParameterManager, mater
       switch (materialCls) {
         case 'PBRMaterial':
           if (options?.animationTimeMs) {
-            _animateParameter(
+            await viewer.utils.animateProperty(
               material as PBRMaterial,
               'albedoColor',
               color.toLinearSpace(),
-              `${BuiltInParameter.Color}.${material.id}`,
+              `${ParameterManager.PARAMETER_ANIMATION_NAME}.${BuiltInParameter.Color}.${material.id}`,
               options.animationTimeMs
             );
           } else {
@@ -213,11 +207,11 @@ export function createBuiltInParameter(parameterManager: ParameterManager, mater
 
         if (target) {
           if (options?.animationTimeMs) {
-            _animateParameter(
+            await viewer.utils.animateProperty(
               target,
               'influence',
               morphTargetValue.value,
-              `${BuiltInParameter.Influence}.${node.name}.${target.name}`,
+              `${ParameterManager.PARAMETER_ANIMATION_NAME}.${BuiltInParameter.Influence}.${node.name}.${target.name}`,
               options.animationTimeMs
             );
           } else {
@@ -233,31 +227,3 @@ export function createBuiltInParameter(parameterManager: ParameterManager, mater
     }
   });
 }
-
-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/parameter/texture-parameter-helper.ts

@@ -2,16 +2,15 @@ import {
   BaseTexture,
   BuiltInParameter,
   Material,
-  MaterialManager,
   PBRMaterial,
   ParameterManager,
-  Scene,
   Texture,
   TextureManager,
+  Viewer,
   ViewerError,
   ViewerErrorIds,
 } from '../..';
-import { embedAssets } from '../svg-helper';
+import { createSvgDataUri, embedAssets } from '../svg-helper';
 import isSvg from 'is-svg';
 
 /**
@@ -51,11 +50,8 @@ export const ParameterTextureChannels = {
 };
 export type ParameterTextureChannelsKeys = keyof typeof ParameterTextureChannels;
 
-export function createBuiltInTextureParameter(
-  parameterManager: ParameterManager,
-  materialManager: MaterialManager,
-  scene: Scene
-): void {
+export function createBuiltInTextureParameter(viewer: Viewer): void {
+  const parameterManager = viewer.parameterManager;
   // create parameter observer for each channel
   (Object.values(ParameterTextureChannels) as ParameterTextureChannelsKeys[]).forEach(channel => {
     parameterManager.setParameterObserver(
@@ -72,8 +68,7 @@ export function createBuiltInTextureParameter(
           // However the rescaling functionality of "Dynamic Textures" is not required and therefore it can be
           // implemented as a plain "Texture"
           const svgWithAssetsEmbedded = await embedAssets(image);
-          // convert into a base64 string, as this can be directly interpreted as "url", at least for Babylon.js
-          url = 'data:image/svg+xml;base64,' + btoa(svgWithAssetsEmbedded);
+          url = createSvgDataUri(svgWithAssetsEmbedded);
         } else if (image.includes('<svg') && image.includes('</svg>')) {
           // seems like the user tried to use a SVG string, as <svg> tags are used
           // inform the user that this is not a valid SVG string
@@ -105,13 +100,13 @@ export function createBuiltInTextureParameter(
           } else if (url) {
             // no texture, or wrong type => create texture from scratch
             // first we check if some settings were provided in the material definition
-            const addMatSettings = await materialManager.getMaterialDefinition(pbrMaterial.id);
+            const addMatSettings = await viewer.materialManager.getMaterialDefinition(pbrMaterial.id);
             const textureSettings = addMatSettings ? _getTextureObjFromParameterChannel(addMatSettings, channel) : {};
 
             // overwrite the name with the url, as this is what the texture parser expects
             (textureSettings as any).name = url;
             // use parser instead of constructor to keep the original texture settings
-            const newTexture = Texture.Parse(textureSettings, scene, '') as Texture;
+            const newTexture = Texture.Parse(textureSettings, viewer.scene, '') as Texture;
 
             if (!newTexture) {
               throw new ViewerError({

package/src/internal/svg-helper.ts

@@ -2,7 +2,7 @@
  * Replaces all supported image & font URLs in the given SVG with their base64 representation.
  */
 export async function embedAssets(svgSrc: string): Promise<string> {
-  const _imageExtensions = ['png', 'gif', 'jpg', 'jpeg', 'svg', 'bmp'];
+  const _imageExtensions = ['png', 'gif', 'jpg', 'jpeg', 'svg', 'bmp', 'webp'];
   const _fontExtensions = ['woff2', 'woff', 'ttf', 'otf'];
   const _assetExtensions = [..._imageExtensions, ..._fontExtensions];
   // Regex copied from https://stackoverflow.com/a/8943487/1273551, not "stress tested"...
@@ -22,6 +22,18 @@ export async function embedAssets(svgSrc: string): Promise<string> {
   return assetFetcherResults.reduce((svgSrc, x) => svgSrc.replace(x.url, x.base64), svgSrc);
 }
 
+/**
+ * Converts an SVG string into a base64-encoded data URI that can be used as a texture URL.
+ * Uses `TextEncoder` to correctly handle non-ASCII characters (e.g. umlauts) before base64-encoding.
+ */
+export function createSvgDataUri(svgSrc: string): string {
+  const utf8Bytes = new TextEncoder().encode(svgSrc);
+  const binary = Array.from(utf8Bytes, b => String.fromCharCode(b)).join('');
+  const dataUri = 'data:image/svg+xml;base64,' + btoa(binary);
+
+  return dataUri;
+}
+
 /**
  * Fetch asset (image or font) and convert it to base64 string representation.
  */

package/src/manager/camera-manager.ts

@@ -11,7 +11,6 @@ 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';
@@ -271,10 +270,11 @@ export class CameraManager {
 
     if (durationMs === 0) {
       // instant movement without animation
+      activeCamera.target = position.target ?? activeCamera.target;
       activeCamera.alpha = position.alpha ?? activeCamera.alpha;
       activeCamera.beta = position.beta ?? activeCamera.beta;
       activeCamera.radius = position.radius ?? activeCamera.radius;
-      activeCamera.target = position.target ?? activeCamera.target;
+      return;
     }
 
     const framesPerSec = 100;
@@ -334,7 +334,7 @@ export class CameraManager {
       );
     }
 
-    await playAnimationGroupOnce(animationGroup, framesPerSec, durationMs);
+    await this.viewer.utils.playAnimationGroupOnce(animationGroup, framesPerSec, durationMs);
   }
 
   /**

package/src/manager/debug-manager.ts

@@ -15,7 +15,7 @@ import {
   Viewer,
   ViewerEvent,
 } from '../index';
-import { getCbnViewerBridge } from '../internal/cbn-viewer-bridge';
+import { CbnViewerBridge } from '../internal/cbn-viewer-bridge';
 import { nodeHasLeftHandedScaling } from '../internal/math-helper';
 
 /**
@@ -57,14 +57,13 @@ export class DebugManager {
    * @returns Signalizes if inspector could be loaded
    */
   public async showInspector(options?: IInspectorOptions): Promise<boolean> {
-    const cbnWindowBridge = getCbnViewerBridge();
     if (process.env.NODE_ENV === 'development') {
       const inspModule = await import(/* webpackChunkName: "inspector"*/ '@babylonjs/inspector');
 
       const parentEl =
         this._parentDomElementForInspector ??
         // fallback to legacy `window.Cbn` call to support "old" cfgrs (pre Editor V2)
-        cbnWindowBridge?.utils?.Viewer3dHelper?.getCfgrParentDomElementForInspector?.();
+        CbnViewerBridge?.utils?.Viewer3dHelper?.getCfgrParentDomElementForInspector?.();
 
       if (!options && parentEl) {
         // special case for usage in Combeenation configurator:
@@ -83,7 +82,7 @@ export class DebugManager {
       return true;
     } else {
       // inspector not available, set according warning message in console
-      if (cbnWindowBridge) {
+      if (CbnViewerBridge) {
         console.warn(`Inspector not loaded. 
 The inspector can only be used in development builds (e.g. during development with watch mode, in the configurator preview, ...)
 but not in production (e.g. production build of Custom JS, published configurator, ...).`);

package/src/manager/material-manager.ts

@@ -9,7 +9,7 @@ import {
   ViewerErrorIds,
   ViewerEvent,
 } from '../index';
-import { getCbnViewerBridge } from '../internal/cbn-viewer-bridge';
+import { CbnViewerBridge } from '../internal/cbn-viewer-bridge';
 import * as CloningHelper from '../internal/cloning-helper';
 import {
   clearInternalMetadataValue,
@@ -201,11 +201,10 @@ export class MaterialManager {
       return definition;
     }
 
-    const cbnWindowBridge = getCbnViewerBridge();
-    if (!definition && cbnWindowBridge?.Assets?.getMaterial) {
+    if (!definition && CbnViewerBridge?.Assets?.getMaterial) {
       // fallback to legacy `Cbn.Assets.getMaterial` call to support "old" cfgrs (pre Editor V2)
       // don't store the result in material defintions, as this code is just here for backwards compatibility`
-      definition = cbnWindowBridge.Assets.getMaterial(materialId) as MaterialDefinition | undefined;
+      definition = CbnViewerBridge.Assets.getMaterial(materialId) as MaterialDefinition | undefined;
     }
 
     if (!definition) {

package/src/manager/parameter-manager.ts

@@ -272,9 +272,7 @@ export class ParameterManager {
   protected _parameterObserver: { [parameterName: ParameterName]: ParameterObserver } = {};
 
   /** @internal */
-  public constructor(protected viewer: Viewer) {
-    this._addBuiltInParameterObservers();
-  }
+  public constructor(protected viewer: Viewer) {}
 
   /**
    * Set parameter value for a certain node and calls the corresponding observer if the value has changed
@@ -417,6 +415,17 @@ export class ParameterManager {
     console.table(printable);
   }
 
+  /**
+   * Parameter observer implementation of default parameters
+   *
+   * @internal
+   */
+  public addBuiltInParameterObservers(): void {
+    createBuiltInParameter(this.viewer);
+    createBuiltInTextureParameter(this.viewer);
+    createPaintableParameter(this.viewer);
+  }
+
   /**
    * Applies all existing parameter entries to a certain "model", as defined in the {@link ModelManager}.\
    * This can be useful when updating the model before showing it in the scene.
@@ -579,15 +588,6 @@ export class ParameterManager {
     return inputValue;
   }
 
-  /**
-   * Parameter observer implementation of default parameters
-   */
-  protected _addBuiltInParameterObservers(): void {
-    createBuiltInParameter(this, this.viewer.materialManager);
-    createBuiltInTextureParameter(this, this.viewer.materialManager, this.viewer.scene);
-    createPaintableParameter(this, this.viewer.scene);
-  }
-
   /**
    * Change parameter value in array of existing parameter entries or create a new entry
    *

package/src/manager/scene-manager.ts

@@ -8,6 +8,7 @@ import {
   CubeTexture,
   DeepPartial,
   IShadowGenerator,
+  InstancedMesh,
   NodeDescription,
   TransformNode,
   Vector3,
@@ -366,11 +367,14 @@ export class SceneManager {
 
     const shadowCasterMeshes: AbstractMesh[] = [];
     this.viewer.scene.meshes.forEach(mesh => {
-      mesh.receiveShadows = !nodeMatchesAnyCriteria(mesh, {
-        isInList: settings?.excludeReceiverNodes,
-        isHtmlAnchorMesh: true,
-        isDimensionLine: true,
-      });
+      // setting `receiveShadows` for instanced meshes has no effect and creates a warning in the console
+      if (!(mesh instanceof InstancedMesh)) {
+        mesh.receiveShadows = !nodeMatchesAnyCriteria(mesh, {
+          isInList: settings?.excludeReceiverNodes,
+          isHtmlAnchorMesh: true,
+          isDimensionLine: true,
+        });
+      }
 
       // exclude "helper meshes" (e.g. skybox, ground, dimension lines, html anchors) here to reduce the size of the
       // poisson filters auto shadow plane calculation, which will result in better shadow resolution

package/src/utils/viewer-utils.ts

@@ -1,4 +1,7 @@
 import {
+  Animation,
+  AnimationGroup,
+  Color3,
   FloatArray,
   Geometry,
   Mesh,
@@ -13,6 +16,8 @@ import {
   Viewer,
 } from '../index';
 
+export type AnimatableProperties = 'albedoColor' | 'position' | 'rotation' | 'scaling' | 'influence';
+
 export type BakeGeometrySettings = {
   keepTransformation?: boolean;
 };
@@ -165,6 +170,76 @@ export class ViewerUtils {
       return this.findParentNode(parent, criteria);
     }
   }
+
+  /**
+   * Animates a single property of a target object from its current value to a given target value.\
+   * Supported property types are defined by {@link AnimatableProperties} (i.e. `number`, `Vector3`, `Color3`).
+   *
+   * @param target The object whose property should be animated
+   * @param property The name of the property to animate. Must be a key of `target` whose value type is supported.
+   * @param value The target value the property should reach at the end of the animation.
+   * @param animationName Name given to the internally created animation group.\
+   *                        Use a stable, unique name per animated property so that concurrent calls can be
+   *                        identified (e.g. `"$parameterAnimation.position.MyNode"`).
+   * @param animationTimeMs Duration of the animation in milliseconds.
+   */
+  public async animateProperty<T, K extends Extract<keyof T, AnimatableProperties>>(
+    target: T,
+    property: K,
+    value: T[K],
+    animationName: 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(animationName);
+
+    const animation = new Animation(property, property, framesPerSec, dataType);
+    animation.setKeys([
+      { frame: 0, value: target[property] },
+      { frame: framesPerSec, value: value },
+    ]);
+    animationGroup.addTargetedAnimation(animation, target);
+
+    await this.playAnimationGroupOnce(animationGroup, framesPerSec, Math.max(animationTimeMs, 0));
+  }
+
+  /**
+   * Plays an animation group exactly in a certain duration, then disposes it.
+   *
+   * The animation group is expected to span exactly `framesPerSec` frames (i.e. one "logical second").\
+   * The speed ratio is derived from that assumption: `speedRatio = 1000 / durationMs`.
+   *
+   * Due to this strict convention, the method is marked as @internal and should not be used directly by a consumer.
+   */
+  public playAnimationGroupOnce(
+    animationGroup: AnimationGroup,
+    framesPerSec: number,
+    durationMs: number
+  ): Promise<void> {
+    if (durationMs <= 0) {
+      animationGroup.dispose();
+      return Promise.resolve();
+    }
+
+    // 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, framesPerSec);
+    });
+  }
 }
 
 /**

package/src/viewer.ts

@@ -301,6 +301,8 @@ export class Viewer {
     // call would already throw
     this._sceneManager.applyDefaultSettingsToScene();
 
+    this._parameterManager.addBuiltInParameterObservers();
+
     this._debugManager.registerAutofocusStartListener();
 
     engine.runRenderLoop(() => {

package/dist/lib-cjs/internal/animation-helper.d.ts

@@ -1,2 +0,0 @@
-import { AnimationGroup } from '../index';
-export declare function playAnimationGroupOnce(animationGroup: AnimationGroup, framesPerSec: number, durationMs: number): Promise<void>;

package/dist/lib-cjs/internal/animation-helper.js

@@ -1,16 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.playAnimationGroupOnce = void 0;
-function playAnimationGroupOnce(animationGroup, framesPerSec, durationMs) {
-    // animation is created for 1 second (100 frames), adjust speed ratio according to desired movement time
-    const speedRatio = 1000 / durationMs;
-    return new Promise(resolve => {
-        animationGroup.onAnimationGroupEndObservable.addOnce(() => {
-            animationGroup.dispose();
-            resolve();
-        });
-        animationGroup.start(false, speedRatio, 0, framesPerSec);
-    });
-}
-exports.playAnimationGroupOnce = playAnimationGroupOnce;
-//# sourceMappingURL=animation-helper.js.map

package/dist/lib-cjs/internal/animation-helper.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"animation-helper.js","sourceRoot":"","sources":["../../../src/internal/animation-helper.ts"],"names":[],"mappings":";;;AAEA,SAAgB,sBAAsB,CACpC,cAA8B,EAC9B,YAAoB,EACpB,UAAkB;IAElB,wGAAwG;IACxG,MAAM,UAAU,GAAG,IAAI,GAAG,UAAU,CAAC;IAErC,OAAO,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE;QACjC,cAAc,CAAC,6BAA6B,CAAC,OAAO,CAAC,GAAG,EAAE;YACxD,cAAc,CAAC,OAAO,EAAE,CAAC;YACzB,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;QACH,cAAc,CAAC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;AACL,CAAC;AAfD,wDAeC"}

package/src/internal/animation-helper.ts

@@ -1,18 +0,0 @@
-import { AnimationGroup } from '../index';
-
-export function playAnimationGroupOnce(
-  animationGroup: AnimationGroup,
-  framesPerSec: number,
-  durationMs: number
-): Promise<void> {
-  // 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, framesPerSec);
-  });
-}