@combeenation/3d-viewer 16.0.0 → 17.0.0

package/src/manager/debug-manager.ts

@@ -1,12 +1,14 @@
 import {
+  AdvancedDynamicTexture,
   AxesViewer,
   BoundingSphere,
   Color3,
-  DynamicTexture,
   IInspectorOptions,
+  Matrix,
+  Mesh,
   MeshBuilder,
-  Scene,
   StandardMaterial,
+  TextBlock,
   TransformNode,
   UtilityLayerRenderer,
   Vector3,
@@ -14,19 +16,10 @@ import {
   ViewerEvent,
 } from '../index';
 
-type DebugAxisKeys = 'X' | 'Y' | 'Z';
-type DebugAxisConfig = { color: Color3; position: Vector3 };
-
 /**
  * Manager for debugging functionalities
  */
 export class DebugManager {
-  protected static _DEBUG_AXIS_MAP: Record<DebugAxisKeys, DebugAxisConfig> = {
-    X: { color: Color3.Red().scale(0.5), position: new Vector3(1, 0, 0) },
-    Y: { color: Color3.Green().scale(0.5), position: new Vector3(0, 1, 0) },
-    Z: { color: Color3.Blue().scale(0.5), position: new Vector3(0, 0, 1) },
-  };
-  protected static _WORLD_COORD_ROOT_KEY = '__world_coordinates__';
   protected static _BOUNDING_SPHERE_KEY = '__bounding_sphere__';
 
   protected _axesViewer: AxesViewer | null = null;
@@ -91,38 +84,63 @@ The inspector can only be used in development builds.`);
   }
 
   /**
-   * Show world coordinate system with given dimension.\
-   * This is especially usefull when working on project with tricky positioning. (e.g. clones)
+   * Displays the coordinate system.\
+   * Shows the local coordinate system of a specified node or the world coordinate system if no node is provided.\
+   * The size defaults to one-third of the scene's bounding sphere radius but can be set manually.
    */
-  public showWorldCoordinates(dimension: number): void {
+  public showCoordinateSystem(node?: TransformNode, size?: number): void {
+    // calculate the default size of not provided
+    if (!size) {
+      const sceneBoundingInfo = this.viewer.calculateBoundingInfo();
+      const radius = sceneBoundingInfo.boundingSphere.radius;
+
+      // takes a third of the radius from scene boundingsphere
+      size = radius * (1 / 3);
+    }
+
     // make sure to remove already existing debug coordinate systems
-    this.hideWorldCoordinates();
+    this.hideCoordinateSystem();
 
     // draw in utility layer, so that there is no interaction with the actually scene content
     // (e.g. glb export, autofocus)
     const utilityLayerScene = UtilityLayerRenderer.DefaultUtilityLayer.utilityLayerScene;
-
-    const worldCoordRoot = new TransformNode(DebugManager._WORLD_COORD_ROOT_KEY, utilityLayerScene);
     // axes viewer coordinate system is a bit too large
     // multiply with unify factor to create arrows which exactly match the length of the input dimension
     const factor = DebugManager._getWorldCoordinatesAxesUnifyFactor();
-    this._axesViewer = new AxesViewer(utilityLayerScene, dimension * factor);
+    this._axesViewer = new AxesViewer(utilityLayerScene, size * factor);
 
-    DebugManager._prepareWorldCoordinateAxis('X', this._axesViewer.xAxis, worldCoordRoot, dimension, utilityLayerScene);
-    DebugManager._prepareWorldCoordinateAxis('Y', this._axesViewer.yAxis, worldCoordRoot, dimension, utilityLayerScene);
-    DebugManager._prepareWorldCoordinateAxis('Z', this._axesViewer.zAxis, worldCoordRoot, dimension, utilityLayerScene);
-  }
+    if (node) {
+      // 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();
+      node.absoluteRotationQuaternion.toRotationMatrix(worldRotMatrix);
 
-  public hideWorldCoordinates(): void {
-    const utilityLayerScene = UtilityLayerRenderer.DefaultUtilityLayer.utilityLayerScene;
+      const xAxis = Vector3.FromArray(worldRotMatrix.m.slice(0, 3)); // First column
+      const yAxis = Vector3.FromArray(worldRotMatrix.m.slice(4, 7)); // Second column
+      const zAxis = Vector3.FromArray(worldRotMatrix.m.slice(8, 11)); // Third column
 
-    this._axesViewer?.dispose();
-    this._axesViewer = null;
+      // consider scaling only for axis direction
+      if (node.absoluteScaling.x < 0) {
+        xAxis.scaleInPlace(-1);
+      }
+      if (node.absoluteScaling.y < 0) {
+        yAxis.scaleInPlace(-1);
+      }
+      if (node.absoluteScaling.z < 0) {
+        zAxis.scaleInPlace(-1);
+      }
 
-    const worldCoordRoot = utilityLayerScene.getTransformNodeByName(DebugManager._WORLD_COORD_ROOT_KEY);
-    if (worldCoordRoot) {
-      worldCoordRoot.dispose(false, true);
+      this._axesViewer.update(node.absolutePosition, xAxis, yAxis, zAxis);
     }
+
+    DebugManager._prepareAxisVisual('X', this._axesViewer.xAxis);
+    DebugManager._prepareAxisVisual('Y', this._axesViewer.yAxis);
+    DebugManager._prepareAxisVisual('Z', this._axesViewer.zAxis);
+  }
+
+  public hideCoordinateSystem(): void {
+    this._axesViewer?.dispose();
+    this._axesViewer = null;
   }
 
   /**
@@ -138,58 +156,6 @@ The inspector can only be used in development builds.`);
     this._removeBoundingSphereForAutofocus();
   }
 
-  /**
-   * Adjust and enhance coordinate axes to fulfill our needs.
-   * - moves nodes into common root
-   * - adds text node
-   */
-  protected static _prepareWorldCoordinateAxis(
-    text: 'X' | 'Y' | 'Z',
-    axis: TransformNode,
-    root: TransformNode,
-    dimension: number,
-    utilityLayerScene: Scene
-  ): void {
-    // create unique names
-    axis.name = `${DebugManager._WORLD_COORD_ROOT_KEY}.${text}`;
-    axis.parent = root;
-
-    // create text mesh via dynamic texture
-    const dynamicTexture = new DynamicTexture(
-      `${DebugManager._WORLD_COORD_ROOT_KEY}.${text}`,
-      50,
-      utilityLayerScene,
-      true
-    );
-    dynamicTexture.hasAlpha = true;
-    // 42.5 is a magic offset, so that the text is vertically centered for font size 50px
-    // horizontal centering works well with the standard behaviour of Babylon.js (setting "null" as "width")
-    dynamicTexture.drawText(text, null, 42.5, 'bold 50px Arial', 'white', 'transparent', true);
-
-    const material = new StandardMaterial(`${DebugManager._WORLD_COORD_ROOT_KEY}.${text}`, utilityLayerScene);
-    material.disableLighting = true;
-    material.emissiveColor = DebugManager._DEBUG_AXIS_MAP[text].color;
-    material.diffuseTexture = dynamicTexture;
-
-    const plane = MeshBuilder.CreatePlane(
-      `${DebugManager._WORLD_COORD_ROOT_KEY}.${text}.TextPlane`,
-      { size: dimension / 10 },
-      utilityLayerScene
-    );
-    // make sure that text is located outside of arrow
-    plane.position = DebugManager._DEBUG_AXIS_MAP[text].position.multiplyByFloats(
-      dimension * 1.05,
-      dimension * 1.05,
-      dimension * 1.05
-    );
-    plane.parent = root;
-    plane.material = material;
-    // will be rendered on top of "default" meshes => taken from Babylon.js repo "AxesViewer" implementation
-    plane.renderingGroupId = 2;
-    // setting billboard mode ensures, that the text is always readable
-    plane.billboardMode = TransformNode.BILLBOARDMODE_ALL;
-  }
-
   /**
    * Calculate factor for creating world coordinate axes with exactly one unit in length
    */
@@ -208,6 +174,42 @@ The inspector can only be used in development builds.`);
     return factor;
   }
 
+  /**
+   * Creates and adds a label with a direction letter at the tip of each axis arrow.\
+   * Also adjust the brightness of the arrow and created label.
+   */
+  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
+    const axisMesh = axisNode.getChildMeshes()[0];
+    const axisMaterial = axisMesh.material as StandardMaterial;
+    const color = axisMaterial.emissiveColor.clone().scale(colorScale);
+
+    axisMaterial.emissiveColor = color;
+
+    const utilityLayerScene = UtilityLayerRenderer.DefaultUtilityLayer.utilityLayerScene;
+    const labelPlane = MeshBuilder.CreatePlane(`${labelText}_label`, { size: labelSize }, 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
+    labelPlane.billboardMode = Mesh.BILLBOARDMODE_ALL;
+
+    // create GUI element
+    const textElement = new TextBlock();
+    textElement.text = labelText;
+    textElement.color = color.toHexString();
+    textElement.fontSize = '100%';
+    textElement.fontFamily = 'Arial';
+    textElement.fontWeight = 'bold';
+
+    const labelTexture = AdvancedDynamicTexture.CreateForMesh(labelPlane);
+    labelTexture.addControl(textElement);
+  }
+
   /**
    * Visualize bounding sphere which is used to zoom in via `autofocusActiveCamera` function
    */

package/src/manager/gltf-export-manager.ts

@@ -19,6 +19,7 @@ import { bakeGeometryOfMesh, createMeshFromInstancedMesh, resetTransformation }
 import { isNodeExcluded } from '../internal/geometry-helper';
 import {
   clearInternalMetadataValue,
+  cloneInternalMetadata,
   getInternalMetadataValue,
   setInternalMetadataValue,
 } from '../internal/metadata-helper';
@@ -42,7 +43,7 @@ export class GltfExportManager {
       shouldExportNode: function (node: Node): boolean {
         if (optimizeForAR) {
           // we explicitely marked nodes, that should be exported in AR mode
-          return getInternalMetadataValue(node, 'exportNode') as boolean;
+          return getInternalMetadataValue(node, 'exportNode');
         } else {
           // use the default export node check (enabled state, exclusion list, etc...)
           return GltfExportManager._shouldExportNode(node, excluded);
@@ -101,9 +102,7 @@ export class GltfExportManager {
 
     const newName = `${material.name}_clone`;
     const clonedMaterial = material.clone(newName)!;
-    // internal metadata may contain large data which slows down the export (CB-10094)
-    // it wasn't an issue for materials yet, but still this is safer than to make a deep clone
-    clonedMaterial._internalMetadata = null;
+    cloneInternalMetadata(material, clonedMaterial);
     const clonedTextures = clonedMaterial.getActiveTextures();
 
     // mark all exported textures, so that they will be deleted after the export
@@ -310,11 +309,7 @@ export class GltfExportManager {
       transformNode instanceof InstancedMesh
         ? createMeshFromInstancedMesh(transformNode, clonedNodeName, clonedParent)
         : transformNode.clone(clonedNodeName, clonedParent, true)!;
-
-    // nodes with node geometry have very large internal metadata, this leads to long export times (CB-10094)
-    // existing internal metadata is not required for the export so we can just delete it
-    // internal metadata will be set some lines beyond!
-    clonedNode._internalMetadata = null;
+    cloneInternalMetadata(transformNode, clonedNode);
 
     // exchange material
     if (clonedNode instanceof Mesh) {

package/src/manager/material-manager.ts

@@ -141,8 +141,6 @@ export class MaterialManager {
       });
     }
 
-    this.viewer.parameterManager.removeParameterEntriesOfMaterial(material);
-
     material.dispose(true, true);
 
     delete this._clonedMaterials[materialId];

package/src/manager/model-manager.ts

@@ -50,6 +50,14 @@ export type NodeNamingStrategy = (node: TransformNode, newModelName: string) =>
 export type TagNamingStrategy = (tag: string, newModelName: string) => string;
 
 export type ModelCloneOptions = {
+  /**
+   * `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
+   * is shared, only the transformation data (e.g. position) can be adjusted.\
+   * Activating this flag can lead to huge performance improvements, especially when working with a large amount of
+   * clones.
+   */
+  createInstance?: boolean;
   nodeNamingStrategy?: NodeNamingStrategy;
   tagNamingStrategy?: TagNamingStrategy;
 };
@@ -61,6 +69,8 @@ type Model = {
   assetContainer: AssetContainer;
   cbnBabylonFileData?: CbnBabylonFileData;
   isClone: boolean;
+  // only set for "instantiated" clones
+  sourceModelName?: string;
   visibilityCallId?: number;
 };
 
@@ -288,16 +298,9 @@ export class ModelManager {
       name: newModelName,
       url: sourceModel.url,
       state: 'loaded',
-      assetContainer: cloneModelAssetContainer(
-        sourceModel.assetContainer,
-        newModelName,
-        {
-          nodeNamingStrategy: options?.nodeNamingStrategy,
-          tagNamingStrategy: options?.tagNamingStrategy,
-        },
-        this.viewer.scene
-      ),
+      assetContainer: cloneModelAssetContainer(sourceModel.assetContainer, newModelName, this.viewer.scene, options),
       isClone: true,
+      sourceModelName: options?.createInstance ? sourceModel.name : undefined,
     };
     this._modelAssets[newModelName] = clonedModel;
 
@@ -329,10 +332,6 @@ export class ModelManager {
       });
     }
 
-    // parameter entries of deleted model can get in the way when recreating a clone with the same node names
-    // that's why it's benefitial to wipe the parameter entries of the model as well after removing it
-    this.viewer.parameterManager.removeParameterEntriesOfModel(model.assetContainer);
-
     model.assetContainer.dispose();
 
     delete this._modelAssets[name];
@@ -444,7 +443,7 @@ export class ModelManager {
       } catch (e) {
         throw new ViewerError({
           id: ViewerErrorIds.AssetLoadingFailed,
-          message: `Error loading model "${model.name}" from url "${model.url}":\n${(e as Error).message}`,
+          message: (e as Error).message,
         });
       }
 
@@ -453,6 +452,15 @@ export class ModelManager {
       [...assetContainer.lights].forEach(light => light.dispose());
       [...assetContainer.cameras].forEach(camera => camera.dispose());
 
+      // materials should be a "global" thing and not assigned to an asset container
+      // this is not relevant in most of the cases, since materials are cropped from babylon models on the CBN server
+      // anyway
+      assetContainer.materials.forEach(material => {
+        this.viewer.scene.addMaterial(material);
+        material._parentContainer = null;
+      });
+      assetContainer.materials = [];
+
       // environment texture and intensity has been overwritten by load asset container function
       this.viewer.scene.environmentTexture = curEnvTexture;
       this.viewer.scene.environmentIntensity = curEnvIntensity;
@@ -473,6 +481,15 @@ export class ModelManager {
    * a smooth model switch behaviour.
    */
   protected async _prepareModelForScene(model: Model): Promise<void> {
+    if (model.sourceModelName) {
+      // source model has to be prepared for scene as well in "instantiate" mode, because materials would not be
+      // loaded otherwise
+      // => the instantiated model only consistes of Instanced Meshes and therefore has no material assignments on
+      // it's own
+      const sourceModel = this._getModel(model.sourceModelName)!;
+      await this._prepareModelForScene(sourceModel);
+    }
+
     await this.viewer.parameterManager.applyAllParameterValuesToModel(model.assetContainer);
     // parameter manager did his job, now apply the deferred materials to all meshes that are not explicitely hidden by
     // the parameter manager

package/src/manager/parameter-manager.ts

@@ -345,20 +345,6 @@ export class ParameterManager {
     await this._applyParameterValues(this._parameterEntries, model);
   }
 
-  /**
-   * Removes existing parameter entries of all nodes of a model.\
-   * This can be useful to clean up the parameter state when removing a (cloned) model.
-   *
-   * @internal
-   */
-  public removeParameterEntriesOfModel(model: IAssetContainer): void {
-    const allNodeNames = [...model.meshes, ...model.transformNodes].map(node => node.name);
-
-    this._parameterEntries = this._parameterEntries.filter(
-      entry => !allNodeNames.includes(entry.subject.nodeName ?? '')
-    );
-  }
-
   /**
    * Applies all parameter values which are targeting a material.\
    * This can be useful when updating a material definition before creating it.
@@ -387,16 +373,6 @@ export class ParameterManager {
     await this._applyParameterValues(parameterEntriesToApply);
   }
 
-  /**
-   * Removes all parameter entries of a certain material.\
-   * This can be useful to clean up the parameter state when removing a (cloned) material.
-   *
-   * @internal
-   */
-  public removeParameterEntriesOfMaterial(material: Material): void {
-    this._parameterEntries = this._parameterEntries.filter(entry => entry.subject.materialName !== material.id);
-  }
-
   /**
    * Applies subset of texture parameter values which are targeting a certain texture channel in a material.\
    * This can be useful when updating texture settings (e.g. uScale) before the texture is actually created.

package/src/manager/texture-manager.ts

@@ -26,7 +26,7 @@ export class TextureManager {
     const indexOfTextureQueryParam = texture.name.lastIndexOf(textureQueryString);
 
     if (isUrl && indexOfTextureQueryParam > -1) {
-      texture.name = texture.name.substring(indexOfTextureQueryParam + textureQueryString.length);
+      texture.displayName = texture.name.substring(indexOfTextureQueryParam + textureQueryString.length);
     }
   }
 }

package/src/viewer.ts

@@ -1,6 +1,7 @@
 import buildInfo from './buildinfo.json';
 import * as Index from './index';
 import {
+  BackgroundMaterial,
   BoundingInfo,
   CameraManager,
   DebugManager,
@@ -199,6 +200,7 @@ export class Viewer {
    * Only takes meshes into considerations that:
    * - are visible
    * - are not excluded by "excludeGeometry" parameter
+   * - do not have a material of type "BackgroundMaterial"
    * - do not have an infinite distance (like sky boxes)
    */
   public calculateBoundingInfo(excludeGeometry?: ExcludedGeometryList): BoundingInfo {
@@ -212,9 +214,12 @@ export class Viewer {
         const hasValidBBoxInfo = mesh.getBoundingInfo().boundingSphere.radius > 0;
         // ignore meshes with infinite distance, typically these are sky boxes
         const hasInfiniteDistance = mesh.infiniteDistance;
+        // ignore meshes with "BackgroundMaterial" - usually a ground or skybox
+        const hasBackgroundMaterial = mesh.material instanceof BackgroundMaterial;
         // ignore excluded meshes
         const isExcluded = excludeGeometry ? isNodeExcluded(mesh, excludeGeometry) : false;
-        return isEnabled && hasValidBBoxInfo && !hasInfiniteDistance && !isExcluded;
+
+        return isEnabled && hasValidBBoxInfo && !hasInfiniteDistance && !hasBackgroundMaterial && !isExcluded;
       })
       .reduce(
         (accBBoxMinMax, curMesh, idx) => {
@@ -240,6 +245,13 @@ export class Viewer {
     // asset manager
     registerCustomCbnBabylonLoaderPlugin();
 
+    // without setting this flag, meshes with billboard mode set would not integrate into the node tree structure,
+    // that means the position would not be updated by the rotation of the parent node
+    // it's a bit dangerous to set this globally, but we need that for:
+    // - `DebugManager.showCoordinateSystem`
+    // - probably dimensions line handling (not implemented yet)
+    TransformNode.BillboardUseParentOrientation = true;
+
     const engine = new Engine(
       this.canvas,
       this._viewerSettings.antialiasing,