@combeenation/3d-viewer 18.4.0-beta1 → 18.5.0

package/src/manager/camera-manager.ts

@@ -380,7 +380,12 @@ export class CameraManager {
       // the idea is to create a dedicated canvas for these elements and merge the result with the main screenshot into
       // a combined canvas
       const screenshotHtmlCanvas = htmlAnchorKeys.length
-        ? await this.viewer.htmlAnchorManager.createScreenshotCanvas(screenshotSize, screenshotCam, htmlAnchorKeys)
+        ? await this.viewer.htmlAnchorManager.createScreenshotCanvas(
+            screenshotSize,
+            screenshotCam,
+            htmlAnchorKeys,
+            excludeNodes
+          )
         : undefined;
 
       const screenshotCombinedCanvas = await createScreenshotCanvas(imageStr3d, screenshotSize, screenshotHtmlCanvas);
@@ -402,7 +407,7 @@ export class CameraManager {
     if (fileName) {
       // rebuild Babylon.js default behaviour: if a file name is given, download the screenshot instead of returning the
       // data string
-      downloadFile(imageStr3d, fileName);
+      downloadFile(imageStr, fileName);
 
       return '';
     } else {

package/src/manager/dimension-line-manager.ts

@@ -1,10 +1,10 @@
-import { Color3, LinesMesh, MeshBuilder, Tags, TransformNode, Vector3, Viewer } from '../index';
+import { Color3, HtmlAnchorOptions, LinesMesh, MeshBuilder, Tags, TransformNode, Vector3, Viewer } from '../index';
 import { merge } from 'lodash-es';
 
 /**
  * Options for dimension line creation
  */
-export type DimensionLineOptions = {
+export type DimensionLineOptions = Pick<HtmlAnchorOptions, 'occlusion' | 'scaling'> & {
   /**
    * Default: `Color3.Black()`
    */
@@ -27,20 +27,6 @@ export type DimensionLineOptions = {
    * Default: no parent node set
    */
   parentNode?: TransformNode;
-  /**
-   * `true`: html elements can be occluded by other meshes
-   * `false`: html elements will always be shown in front of the scene
-   *
-   * Default: `false`
-   */
-  hideIfOccluded: boolean;
-  /**
-   * `true`: html element size is relative to camera distance, just like a "normal" 3d object
-   * `false`: html element size remains constant
-   *
-   * Default: `false`
-   */
-  scaleWithCameraDistance: boolean;
   /**
    * Optional callback for label text creation.\
    * Provides calculated length from `startPoint` and `endPoint` as parameter in meters.
@@ -64,8 +50,6 @@ export class DimensionLineManager {
   protected _defaultLineOptions: DimensionLineOptions = {
     lineColor: Color3.Black(),
     closingLineHeight: 0.05,
-    hideIfOccluded: false,
-    scaleWithCameraDistance: false,
     labelTextCb: (lengthM): string => {
       const lengthRounded = Math.round(lengthM * 1000 * 100) / 100;
       return `${lengthRounded} mm`;
@@ -123,8 +107,8 @@ export class DimensionLineManager {
       closingLineHeight,
       closingLineDirection: closingLineDirectionIn,
       parentNode,
-      hideIfOccluded,
-      scaleWithCameraDistance,
+      occlusion,
+      scaling,
       labelTextCb,
       labelCssClass,
     } = resDefaultOptions;
@@ -151,7 +135,7 @@ export class DimensionLineManager {
     linesMesh.position = lineCenter;
     linesMesh.color = lineColor;
     // rendering group id 1 reserved for html anchor meshes, which are required for occlusion checking
-    linesMesh.renderingGroupId = hideIfOccluded ? 0 : 2;
+    linesMesh.renderingGroupId = occlusion?.hideIfOccluded ? 0 : 2;
     // tag can be used to exclude dimension lines from autofocus or gltf export
     Tags.AddTagsTo(linesMesh, DimensionLineManager.DIMENSION_LINE_KEY);
     if (parentNode) {
@@ -185,8 +169,8 @@ export class DimensionLineManager {
     this.viewer.htmlAnchorManager.addHtmlAnchor(name, span, Vector3.Zero(), {
       parentNode: linesMesh,
       group: DimensionLineManager.DIMENSION_LINE_KEY,
-      hideIfOccluded,
-      scaleWithCameraDistance,
+      occlusion,
+      scaling,
     });
 
     this._dimensionLineObjs[name] = { linesMesh, htmlLabelName };

package/src/manager/html-anchor-manager.ts

@@ -4,18 +4,68 @@ import {
   Camera,
   DimensionLineManager,
   MeshBuilder,
+  NodeDescription,
   Ray,
   ScreenshotSize,
   StandardMaterial,
-  Tags,
   TransformNode,
   Vector3,
   Viewer,
   Viewport,
 } from '..';
 import { getInternalMetadataValue, setInternalMetadataValue } from '../internal/metadata-helper';
+import { nodeMatchesAnyCriteria } from '../internal/node-helper';
 import html2canvas from 'html2canvas';
 
+export type HtmlAnchorOcclusionOptions = {
+  /**
+   * `true`: html elements can be occluded by other meshes
+   * `false`: html elements will always be shown in front of the scene
+   *
+   * Default: `false`
+   */
+  hideIfOccluded: boolean;
+  /**
+   * Size of dummy mesh for occlusion check
+   * Smaller values result in a more precise occlusion check around the center of the anchor.
+   * Too small values can lead to flickering of the html element.
+   *
+   * Default: 0.01
+   */
+  anchorMeshSize?: number;
+};
+
+export type HtmlAnchorScalingOptions = {
+  /**
+   * `true`: html element size is relative to camera distance, just like a "normal" 3d object
+   * `false`: html element size remains constant and `referenceScale`, `minScale` and `maxScale` will have no effect
+   *
+   * Default: `false`
+   */
+  scaleWithCameraDistance: boolean;
+  /**
+   * Basis factor for converting camera distance in Babylon.js units to pixels.
+   * Find a suitable value for your project by trial and error, whereas larger values will make the html anchor elements
+   * larger as well.
+   *
+   * Default: 1
+   */
+  referenceScale?: number;
+  /**
+   * Can be used to limit the calculated scale value so that a html anchor element is still readable/clickable if the
+   * camera is far zoomed out.
+   *
+   * Default: undefined (no limit)
+   */
+  minScale?: number;
+  /**
+   * Max limit cap when zooming the camera in to avoid html anchor elements getting too large.
+   *
+   * Default: undefined (no limit)
+   */
+  maxScale?: number;
+};
+
 export type HtmlAnchorOptions = {
   /**
    * Associated anchor mesh will be created underneath this parent node.\
@@ -27,19 +77,13 @@ export type HtmlAnchorOptions = {
    */
   group?: string;
   /**
-   * `true`: html elements can be occluded by other meshes
-   * `false`: html elements will always be shown in front of the scene
-   *
-   * Default: `false`
+   * Occlusion options, see {@link HtmlAnchorOcclusionOptions}
    */
-  hideIfOccluded?: boolean;
+  occlusion?: HtmlAnchorOcclusionOptions;
   /**
-   * `true`: html element size is relative to camera distance, just like a "normal" 3d object
-   * `false`: html element size remains constant
-   *
-   * Default: `false`
+   * Scaling options, see {@link HtmlAnchorScalingOptions}
    */
-  scaleWithCameraDistance?: boolean;
+  scaling?: HtmlAnchorScalingOptions;
   /**
    * Activates/deactivates `pointer-events` CSS class of anchor element.\
    * Set this to `true` if the html element should be interactive (e.g. button)
@@ -122,7 +166,7 @@ export class HtmlAnchorManager {
       return;
     }
 
-    const { parentNode, enablePointerEvents } = options ?? {};
+    const { parentNode, occlusion, enablePointerEvents } = options ?? {};
 
     // create a parent for the input html element, which will receive the updated style and transform data
     // in this way the original input element remains untouched
@@ -141,7 +185,9 @@ export class HtmlAnchorManager {
 
     // NOTE: creates a sphere with fixed size, which could be problematic in scene with "strange" dimensions
     // add a property for the sphere size if required
-    const anchorMesh = MeshBuilder.CreateSphere(`${HtmlAnchorManager._HTML_ANCHOR_KEY}_${name}`, { diameter: 0.01 });
+    const anchorMesh = MeshBuilder.CreateSphere(`${HtmlAnchorManager._HTML_ANCHOR_KEY}_${name}`, {
+      diameter: occlusion?.anchorMeshSize ?? 0.01,
+    });
     anchorMesh.position = position;
     anchorMesh.parent = parentNode ?? null;
     // anchor mesh will be invisible, we only need it for positioning and occlusion check
@@ -203,7 +249,8 @@ export class HtmlAnchorManager {
   public async createScreenshotCanvas(
     size: ScreenshotSize,
     camera: ArcRotateCamera,
-    htmlAnchorKeys: string[]
+    htmlAnchorKeys: string[],
+    excludeNodes?: NodeDescription[]
   ): Promise<HTMLCanvasElement> {
     const canvasParentHtmlElement = this.viewer.canvas?.parentElement;
     if (!canvasParentHtmlElement) {
@@ -242,7 +289,8 @@ export class HtmlAnchorManager {
         size.canvasHeight,
         baseScale,
         true,
-        options
+        options,
+        excludeNodes
       );
     });
 
@@ -291,9 +339,12 @@ export class HtmlAnchorManager {
     height: number,
     baseScale: number,
     useRayHitTestForOcclusionCheck: boolean,
-    options?: HtmlAnchorOptions
+    options?: HtmlAnchorOptions,
+    excludeNodes?: NodeDescription[]
   ): void {
-    const { hideIfOccluded, scaleWithCameraDistance } = options ?? {};
+    const { occlusion, scaling } = options ?? {};
+    const { hideIfOccluded } = occlusion ?? {};
+    const { scaleWithCameraDistance, referenceScale, minScale, maxScale } = scaling ?? {};
 
     const viewMatrix = camera.getViewMatrix();
     const projectionMatrix = camera.getProjectionMatrix();
@@ -307,20 +358,27 @@ export class HtmlAnchorManager {
       new Viewport(0, 0, width, height)
     );
 
+    const meshWorldPos = anchorMesh.getAbsolutePosition();
+    // calculate camera world position manually, as there is no help function like for meshes
+    const camWorldMatrix = camera.computeWorldMatrix();
+    const camWorldPos = camWorldMatrix.getTranslation();
+    const distance = Vector3.Distance(meshWorldPos, camWorldPos);
+    const camYWindow = distance * Math.tan(camera.fov / 2);
+
     // base scale is used if width and height don't equal the viewer canvas, which is the case for screenshots
     let scale = baseScale;
     if (scaleWithCameraDistance) {
-      const meshWorldPos = anchorMesh.getAbsolutePosition();
-      // calculate camera world position manually, as there is no help function like for meshes
-      const camWorldMatrix = camera.computeWorldMatrix();
-      const camWorldPos = camWorldMatrix.getTranslation();
-      const distance = Vector3.Distance(meshWorldPos, camWorldPos);
-      const frustumSlopeY = Math.tan(camera.fov / 2);
       // if the distance from camera to mesh gets larger, the html elements scaling will be decreased
       // we also consider the cameras FOV, so scale 1 means, that the resulting vertical frustum of the camera
       // distance equals 1
-      // ...this is probably too small in some scenarios, so we might have to add a general scale setting here
-      scale *= 1 / (distance * frustumSlopeY);
+      scale *= (referenceScale ?? 1) / camYWindow;
+      // apply scale caps
+      if (minScale !== undefined) {
+        scale = Math.max(scale, minScale);
+      }
+      if (maxScale !== undefined) {
+        scale = Math.min(scale, maxScale);
+      }
     }
 
     const elementXOffset = (parentHtmlElement.offsetWidth * scale) / 2;
@@ -350,7 +408,7 @@ export class HtmlAnchorManager {
         const ray = new Ray(camera.position, camDirection);
         const hit = this.viewer.scene.pickWithRay(
           ray,
-          mesh => !Tags.MatchesQuery(mesh, DimensionLineManager.DIMENSION_LINE_KEY),
+          mesh => !nodeMatchesAnyCriteria(mesh, { isInList: excludeNodes, isDimensionLine: true }),
           false
         );
         isOccluded = hit?.pickedMesh !== anchorMesh;

package/src/manager/material-manager.ts

@@ -1,9 +1,9 @@
 import {
   AbstractMesh,
-  BaseTexture,
   Material,
   StandardMaterial,
   TagNamingStrategy,
+  TextureManager,
   Viewer,
   ViewerError,
   ViewerErrorIds,
@@ -188,9 +188,15 @@ export class MaterialManager {
 
     await this.viewer.parameterManager.applyParameterValuesToMaterial(material);
 
-    const matReadyProms = [
-      new Promise<void>(resolve => BaseTexture.WhenAllReady(material.getActiveTextures(), resolve)),
-    ];
+    const texturesLoadProm = async (): Promise<void> => {
+      const errTextureName = await TextureManager.waitTexturesLoadedOrFailed(material.getActiveTextures());
+      if (errTextureName) {
+        console.warn(
+          `Couldn't load texture "${errTextureName}" of material "${material.id}", material still got created`
+        );
+      }
+    };
+    const matReadyProms = [texturesLoadProm()];
 
     if (mesh) {
       // this promise should only take some time on the first call of the corresponding shader (eg: PBRMaterial shader)

package/src/manager/texture-manager.ts

@@ -1,4 +1,4 @@
-import { BaseTexture, Viewer } from '../index';
+import { BaseTexture, Texture, Viewer } from '../index';
 
 /**
  * Manager for texture related tasks, like renaming textures that are based on Combeenation image assets.\
@@ -7,6 +7,28 @@ import { BaseTexture, Viewer } from '../index';
  * @internal
  */
 export class TextureManager {
+  /**
+   * Basic textures loading check `BaseTexture.WhenAllReady` doesn't consider loading errors, which easily leads to a
+   * deadlock. (see CB-10769)
+   * This implementation listens for loading errors in the associated textures and aborts the promise accordingly.
+   *
+   * @returns (display) name of the texture that failed to load, or "" if every texture loaded successfully
+   */
+  public static async waitTexturesLoadedOrFailed(textures: BaseTexture[]): Promise<string> {
+    const texturesReadyProm = new Promise<string>(resolve => BaseTexture.WhenAllReady(textures, () => resolve('')));
+    const textureLoadErrorProm = new Promise<string>(resolve => {
+      const errorObserver = Texture.OnTextureLoadErrorObservable.add(errTexture => {
+        const activeTextureUniqueIds = textures.map(x => x.uniqueId);
+        if (activeTextureUniqueIds.includes(errTexture.uniqueId)) {
+          resolve(errTexture.displayName ?? errTexture.name);
+          errorObserver.remove();
+        }
+      });
+    });
+
+    return Promise.race([texturesReadyProm, textureLoadErrorProm]);
+  }
+
   public constructor(protected viewer: Viewer) {
     this.viewer.scene.onNewTextureAddedObservable.add(texture => this._onTextureAdded(texture));
   }