@combeenation/3d-viewer 17.1.0 → 18.0.0-beta2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combeenation/3d-viewer",
-  "version": "17.1.0",
+  "version": "18.0.0-beta2",
   "description": "Combeenation 3D Viewer",
   "homepage": "https://github.com/Combeenation/3d-viewer#readme",
   "bugs": {
@@ -41,15 +41,20 @@
     "pub-beta": "npm run dist-cjs && npm publish --tag beta",
     "pub-final": "npm run dist-cjs && npm publish",
     "pub-rc": "npm run dist-cjs && npm publish --tag rc",
-    "replace-version": "cross-env-shell replace \"@VERSION@\" $npm_package_version dist -r"
+    "replace-version": "cross-env-shell replace \"@VERSION@\" $npm_package_version dist -r",
+    "sleep5s": "node -e \"setTimeout(() => process.exit(0), 5000)\"",
+    "start-asset-server": "cross-env NODE_ENV='production' webpack serve --config build/webpack.test.conf.js",
+    "test": "vitest",
+    "test-delayed": "npm run sleep5s && npm run test"
   },
   "prettier": "@combeenation/prettier-config",
   "dependencies": {
-    "@babylonjs/core": "7.43.0",
-    "@babylonjs/gui": "7.43.0",
-    "@babylonjs/loaders": "7.43.0",
-    "@babylonjs/serializers": "7.43.0",
+    "@babylonjs/core": "7.47.3",
+    "@babylonjs/gui": "7.47.3",
+    "@babylonjs/loaders": "7.47.3",
+    "@babylonjs/serializers": "7.47.3",
     "eventemitter3": "4.0.7",
+    "html2canvas": "1.4.1",
     "is-svg": "^5.0.0",
     "lodash-es": "4.17.21"
   },
@@ -63,6 +68,7 @@
     "cross-env": "7.0.3",
     "eslint": "8.25.0",
     "html-webpack-plugin": "5.5.0",
+    "jsdom": "^26.0.0",
     "prettier": "2.7.1",
     "replace": "1.2.1",
     "rimraf": "3.0.2",
@@ -71,6 +77,7 @@
     "typedoc": "0.23.15",
     "typedoc-plugin-merge-modules": "4.0.1",
     "typescript": "4.8.4",
+    "vitest": "2.1.8",
     "webpack": "5.74.0",
     "webpack-bundle-analyzer": "4.6.1",
     "webpack-cli": "4.10.0",
@@ -78,16 +85,19 @@
     "webpack-merge": "5.8.0"
   },
   "optionalDependencies": {
-    "@babylonjs/gui-editor": "7.43.0",
-    "@babylonjs/inspector": "7.43.0",
-    "@babylonjs/materials": "7.43.0",
-    "@babylonjs/node-editor": "7.43.0",
-    "@babylonjs/node-geometry-editor": "7.43.0"
+    "@babylonjs/gui-editor": "7.47.3",
+    "@babylonjs/inspector": "7.47.3",
+    "@babylonjs/materials": "7.47.3",
+    "@babylonjs/node-editor": "7.47.3",
+    "@babylonjs/node-geometry-editor": "7.47.3"
   },
   "dependenciesComments": {
-    "@babylonjs": "Latest version 7.43.0 comes with getters for tagged entities in asset containers, as requested by us (see [PR](https://github.com/BabylonJS/Babylon.js/pull/16029))"
+    "@babylonjs": "Latest version 7.47.3 added lower camera target y limit, as requested from us (https://github.com/BabylonJS/Babylon.js/pull/16125)"
   },
   "optionalDependenciesComments": {
     "@babylonjs": "Defining the inspector package (and it's dependencies) as optional is required to omit these packages in the production build of the CBN react-app (see CB-9269)"
+  },
+  "scriptsComments": {
+    "test-delayed": "Didn't manage to wait 5 seconds for starting up the asset server as an individual VS Code task, therefore it's solved as npm script"
   }
 }

package/src/index.ts

@@ -19,7 +19,10 @@ export * from '@babylonjs/core/Cameras/camera';
 export * from '@babylonjs/core/Culling';
 export * from '@babylonjs/core/Debug/axesViewer';
 export * from '@babylonjs/core/Debug/debugLayer';
+export * from '@babylonjs/core/Engines/abstractEngine';
 export * from '@babylonjs/core/Engines/engine';
+export * from '@babylonjs/core/Engines/Extensions/engine.query';
+export * from '@babylonjs/core/Engines/nullEngine';
 export * from '@babylonjs/core/Engines/thinEngine';
 export * from '@babylonjs/core/Lights';
 export * from '@babylonjs/core/Loading';
@@ -31,14 +34,17 @@ export * from '@babylonjs/core/Maths';
 export * from '@babylonjs/core/Meshes/abstractMesh';
 export * from '@babylonjs/core/Meshes/geometry';
 export * from '@babylonjs/core/Meshes/instancedMesh';
+export * from '@babylonjs/core/Meshes/linesMesh';
 export * from '@babylonjs/core/Meshes/mesh';
 export * from '@babylonjs/core/Meshes/meshBuilder';
 export * from '@babylonjs/core/Meshes/transformNode';
+export * from '@babylonjs/core/Misc/observable';
 export * from '@babylonjs/core/Misc/interfaces/screenshotSize';
 export * from '@babylonjs/core/Misc/screenshotTools';
 export * from '@babylonjs/core/Misc/tags';
 export * from '@babylonjs/core/Morph';
 export * from '@babylonjs/core/node';
+export * from '@babylonjs/core/Rendering/boundingBoxRenderer';
 export * from '@babylonjs/core/Rendering/utilityLayerRenderer';
 export * from '@babylonjs/core/scene';
 export * from '@babylonjs/core/types';
@@ -64,9 +70,11 @@ export * from '@babylonjs/core/Materials/Node';
 export * from './viewer';
 export * from './viewer-error';
 export * from './manager/camera-manager';
+export * from './manager/dimension-line-manager';
 export * from './manager/debug-manager';
 export * from './manager/event-manager';
 export * from './manager/gltf-export-manager';
+export * from './manager/html-anchor-manager';
 export * from './manager/material-manager';
 export * from './manager/model-manager';
 export * from './manager/parameter-manager';

package/src/internal/asset-helper.ts

@@ -0,0 +1,115 @@
+import { AssetContainer, SceneAssetSettings, SceneLoader, Viewer, ViewerError, ViewerErrorIds } from '..';
+import { CbnBabylonFileData, ExtendedAssetContainer } from './cbn-custom-babylon-loader-plugin';
+import { getInternalMetadataValue } from './metadata-helper';
+
+export type AssetState = 'notLoaded' | 'loading' | 'loaded' | 'inScene';
+
+/**
+ * Common base asset for model and scene asset
+ */
+export type BaseAsset = {
+  name: string;
+  url: string;
+  state: AssetState;
+  assetContainer: AssetContainer;
+};
+
+/**
+ * Help function for loading asset as asset container, with some special tweaks and fixes that we need in our CBN
+ * environment:
+ * - reconstruct current environment texture and intensity, as it get overwritten by Babylon.js basic loading function
+ * - explicitely define plugin extension for gzipped babylon files
+ * - extract and return cbn custom data from babylon file
+ * - crop materials from asset containers and add them to scene directly, as we treat materials as a global entity,
+ *   which can be used from all models alike
+ *
+ * This function is used by model and scene asset alike.
+ */
+export async function loadAsset(
+  asset: BaseAsset,
+  viewer: Viewer
+): Promise<{ cbnData?: CbnBabylonFileData; sceneSettingsData?: SceneAssetSettings }> {
+  asset.state = 'loading';
+  const curEnvTexture = viewer.scene.environmentTexture;
+  const curEnvIntensity = viewer.scene.environmentIntensity;
+
+  // CB-9240: Babylon.js doesn't recognize gzipped babylon files (`.babylon.gz`) as such, leading to a warning
+  // message, therefore we overwrite the plugin extension actively for such files
+  let pluginExtension;
+  try {
+    // URL constructor can throw for "valid" URL, which happened to be the case for the test asset environment where
+    // the urls are relative (starting with ".")
+    const urlObj = new URL(asset.url);
+    if (urlObj.pathname.endsWith('.babylon.gz')) {
+      pluginExtension = '.babylon';
+    }
+  } catch (e) {}
+
+  let extendedAssetContainer;
+  try {
+    extendedAssetContainer = (await SceneLoader.LoadAssetContainerAsync(
+      '',
+      asset.url,
+      viewer.scene,
+      undefined,
+      pluginExtension
+    )) as ExtendedAssetContainer;
+  } catch (e) {
+    throw new ViewerError({
+      id: ViewerErrorIds.AssetLoadingFailed,
+      message: (e as Error).message,
+    });
+  }
+
+  const { cbnData, sceneSettingsData } = extendedAssetContainer;
+  delete extendedAssetContainer.cbnData;
+  delete extendedAssetContainer.sceneSettingsData;
+
+  // from here it's a basic asset container again
+  const assetContainer = extendedAssetContainer as AssetContainer;
+
+  // materials should be a "global" thing and not assigned to an asset container
+  // this is not relevant for model assets in most of the cases, since materials are cropped from babylon models on the
+  // CBN server anyway
+  assetContainer.materials.forEach(material => {
+    viewer.scene.addMaterial(material);
+    material._parentContainer = null;
+    viewer.parameterManager.applyParameterValuesToMaterial(material);
+  });
+  assetContainer.materials = [];
+
+  // environment texture and intensity has been overwritten by load asset container function
+  viewer.scene.environmentTexture = curEnvTexture;
+  viewer.scene.environmentIntensity = curEnvIntensity;
+
+  asset.assetContainer = assetContainer;
+  asset.state = 'loaded';
+
+  return { cbnData, sceneSettingsData };
+}
+
+/**
+ * Help function for applying parameter values and "deferred" material to asset (model or scene asset), before using it
+ * in the scene
+ */
+export async function prepareAssetForScene(asset: BaseAsset, viewer: Viewer): Promise<void> {
+  await viewer.parameterManager.applyAllParameterValuesToModel(asset.assetContainer);
+  // parameter manager did his job, now apply the deferred materials to all meshes that are not explicitely hidden by
+  // the parameter manager
+  await _applyDeferredMaterialsForAllVisibleMeshes(asset, viewer);
+}
+
+/**
+ * Creates and assigns each "deferred" material to the corresponding mesh, if the mesh is visible.
+ * Model should be ready to use immediately after this function has done it's job.
+ */
+async function _applyDeferredMaterialsForAllVisibleMeshes(asset: BaseAsset, viewer: Viewer): Promise<void> {
+  const setMaterialProms = asset.assetContainer.meshes.map(async mesh => {
+    const deferredMaterial = getInternalMetadataValue(mesh, 'deferredMaterial');
+    const visible = viewer.parameterManager.getNestedVisibilityParameterValueOfNode(mesh);
+    if (deferredMaterial && visible) {
+      await viewer.materialManager.setMaterialOnMesh(deferredMaterial as string, mesh);
+    }
+  });
+  await Promise.all(setMaterialProms);
+}

package/src/internal/cbn-custom-babylon-loader-plugin.ts

@@ -1,9 +1,10 @@
 import {
   AssetContainer,
-  ExtendedAssetContainer,
+  Color4,
   ISceneLoaderPlugin,
   InstancedMesh,
   ParsedDecalConfiguration,
+  SceneAssetSettings,
   SceneLoader,
   ViewerError,
   ViewerErrorIds,
@@ -13,6 +14,23 @@ import { setInternalMetadataValue } from './metadata-helper';
 import { deleteAllTags, getTagsAsStrArr, setTagsAsString } from './tags-helper';
 import { isArray, isString } from 'lodash-es';
 
+/**
+ * Contains cbn custom data, like decals or scene settings.
+ * This is just a temporary type, as the `loadAssetContainer` function only returns an asset container, which can be
+ * altered by our file loader plugin.
+ * After loading the model, `cbnData` is cropped and a pure asset container is available for further processing.
+ * @internal
+ */
+export class ExtendedAssetContainer extends AssetContainer {
+  cbnData?: CbnBabylonFileData;
+  sceneSettingsData?: SceneAssetSettings;
+}
+
+/**
+ * @internal
+ */
+export type CbnBabylonFileData = { decals?: ParsedDecalConfiguration[] };
+
 type DataWithMeshes = { meshes: unknown[] };
 type DataWithDecalConfigurations = { cbnData: { decals: unknown[] } };
 
@@ -59,7 +77,11 @@ export function registerCustomCbnBabylonLoaderPlugin(): void {
     load: previousLoaderPlugin.load,
     loadAssetContainer: (scene, data, rootUrl, onError): ExtendedAssetContainer => {
       const dataParsed = JSON.parse(data as string);
-      const importedContainer = previousLoaderPlugin.loadAssetContainer(scene, data, rootUrl);
+      // root url parameter is left empty for the following reasons:
+      // - cube texture creation (for environment) breaks, as Babylon.js tries to prefix absolute paths (e.g. from
+      //   Babylon.js server) with the root url
+      // - we always have absolute paths anyway => links to 3d model, material & textures assets
+      const importedContainer = previousLoaderPlugin.loadAssetContainer(scene, data, '');
 
       _addMissingMaterialMetadata(dataParsed, importedContainer);
       _reconstructTagsForInstancedMeshes(dataParsed, importedContainer);
@@ -73,9 +95,14 @@ export function registerCustomCbnBabylonLoaderPlugin(): void {
         onError?.((e as Error).message);
       }
 
-      // add `cbnData` to output asset container, so that this information can be store as metadata for the model
+      // add `cbnData` to output asset container, so that this information can be stored as metadata for the model
+      // same with `sceneSettingsData`, which is used in the scene asset
       const extendedContainer = importedContainer as ExtendedAssetContainer;
       extendedContainer.cbnData = dataParsed.cbnData;
+      extendedContainer.sceneSettingsData = {
+        environmentIntensity: dataParsed.environmentIntensity,
+        clearColor: dataParsed.clearColor && Color4.FromArray(dataParsed.clearColor),
+      };
 
       return extendedContainer;
     },

package/src/internal/cloning-helper.ts

@@ -186,7 +186,7 @@ function _cloneNode(
     // making deep copies of the node metadata might be an optional flag in the cloning functions in the future
 
     // ATM the assignment from clone to source is needed for reassigning instanced meshes after cloning
-    // may be usefull for other node types in the future as well
+    // may be useful for other node types in the future as well
     setInternalMetadataValue(clone, 'cloneSource', node.uniqueId);
     setInternalMetadataValue(node, 'cloneTarget', clone.uniqueId);
 

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

@@ -73,17 +73,21 @@ export function createBuiltInTextureParameter(parameterManager: ParameterManager
           const texture = _getTextureFromParameterChannel(pbrMaterial, channel);
 
           if (texture) {
-            // create a clone of the texture, in this way we can load the image before assigning it to the material
-            // channel
-            const clonedTexture = texture.clone();
-            // update texture and await loading time right away
-            await new Promise<void>(resolve => clonedTexture.updateURL(url, undefined, resolve));
-
-            _assignTextureParameterChannel(clonedTexture, pbrMaterial, channel);
+            if (url) {
+              // create a clone of the texture, in this way we can load the image before assigning it to the material
+              // channel
+              const clonedTexture = texture.clone();
+              // update texture and await loading time right away
+              await new Promise<void>(resolve => clonedTexture.updateURL(url, undefined, resolve));
+
+              _assignTextureParameterChannel(clonedTexture, pbrMaterial, channel);
+            } else {
+              _removeFromTextureParameterChannel(pbrMaterial, channel);
+            }
 
             // dispose old texture
             texture.dispose();
-          } else {
+          } 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 window.Cbn?.Assets.getMaterial(pbrMaterial.id);
@@ -341,6 +345,19 @@ function _assignTextureParameterChannel(
   }
 }
 
+/**
+ * Remove runtime texture from dedicated channel in the PBR material
+ */
+function _removeFromTextureParameterChannel(pbrMaterial: PBRMaterial, channel: ParameterTextureChannelsKeys): void {
+  if (channel === 'metallicRoughnessTexture') {
+    pbrMaterial.metallicTexture = null;
+  } else if (channel === 'detailmapTexture') {
+    pbrMaterial.detailMap.texture = null;
+  } else {
+    pbrMaterial[channel] = null;
+  }
+}
+
 /**
  * Similar to `_getTextureFromParameterChannel`, whereas the input is a plain JSON object instead of a runtime material
  */

package/src/manager/camera-manager.ts

@@ -4,7 +4,6 @@ import {
   ArcRotateCamera,
   BoundingSphere,
   ExcludedGeometryList,
-  IScreenshotSize,
   ScreenshotTools,
   Vector3,
   Viewer,
@@ -64,6 +63,11 @@ export type ScreenshotSettings = {
   autofocusScene?: boolean;
   /** Optional list of geometry to be excluded from consideration */
   exclude?: ExcludedGeometryList;
+  /**
+   * Optional list of html anchor groups (see {@link HtmlAnchorManager}), that should be excluded from the screenshot.\
+   * Excludes ALL html anchor groups if set to `true`.
+   */
+  excludeHtmlAnchorGroups?: string[] | true;
   /**
    * "MIME type" of the returned screenshot image, defaults to `image/png`
    *
@@ -89,11 +93,27 @@ export type ScreenshotSettings = {
   quality?: number;
 };
 
+/**
+ * Internal data type for screenshot sizing.
+ * `imageWidth/Height` defines the size of the final image.
+ * `canvasWidth/Height` is the size of the canvas from which the screenshot is taken.
+ * Canvas size always has the same aspect ratio as the viewport and is larger than image size, as the final image may be
+ * cropped.
+ *
+ * @internal
+ */
+export type ScreenshotSize = {
+  imageWidth: number;
+  imageHeight: number;
+  canvasWidth: number;
+  canvasHeight: number;
+};
+
 /**
  * Manager for camera related tasks
  */
 export class CameraManager {
-  public static readonly CAMERA_ANIMATION_NAME = '__cameraAnimation__';
+  public static readonly CAMERA_ANIMATION_NAME = '$cameraAnimation';
 
   /** @internal */
   public static readonly DEFAULT_CAMERA_POSITION: CameraPosition = {
@@ -112,7 +132,7 @@ export class CameraManager {
 
   protected static readonly _DEFAULT_AUTOFOCUS_RADIUS_FACTOR = 1;
   protected static readonly _DEFAULT_CAM_SPEED_MS = 250;
-  protected static readonly _SCREENSHOT_CAMERA_NAME = '__screenshotCamera__';
+  protected static readonly _SCREENSHOT_CAMERA_NAME = '$screenshotCamera';
 
   /** @internal */
   public constructor(protected viewer: Viewer) {}
@@ -131,7 +151,7 @@ export class CameraManager {
     }
 
     // get bounding box of all visible meshes, this is the base for the autofocus algorithm
-    const boundingInfo = this.viewer.calculateBoundingInfo(settings?.exclude);
+    const boundingInfo = this.viewer.sceneManager.calculateBoundingInfo(settings?.exclude);
     // optionally show bounding sphere for debugging purpose
     this.viewer.eventManager.fireEvent(ViewerEvent.AutofocusStart, boundingInfo.boundingSphere);
 
@@ -269,19 +289,38 @@ export class CameraManager {
    * The result is a string containing a base64 encoded image.
    */
   public async createScreenshot(settings?: ScreenshotSettings): Promise<string> {
+    const {
+      width,
+      height,
+      alpha,
+      beta,
+      radius,
+      target,
+      autofocusScene,
+      exclude,
+      excludeHtmlAnchorGroups,
+      fileName,
+      samples,
+      antialiasing,
+      renderSprites,
+      enableStencilBuffer,
+      useLayerMask,
+      quality,
+    } = settings ?? {};
+
     const screenshotCam = this.viewer.scene.activeCamera?.clone(
       CameraManager._SCREENSHOT_CAMERA_NAME
     ) as ArcRotateCamera;
-    const boundingInfo = settings?.autofocusScene ? this.viewer.calculateBoundingInfo(settings.exclude) : undefined;
+    const boundingInfo = autofocusScene ? this.viewer.sceneManager.calculateBoundingInfo(exclude) : undefined;
 
-    if (settings?.alpha !== undefined) {
-      screenshotCam.alpha = settings.alpha;
+    if (alpha !== undefined) {
+      screenshotCam.alpha = alpha;
     }
-    if (settings?.beta !== undefined) {
-      screenshotCam.beta = settings.beta;
+    if (beta !== undefined) {
+      screenshotCam.beta = beta;
     }
-    if (settings?.radius !== undefined) {
-      screenshotCam.radius = settings.radius;
+    if (radius !== undefined) {
+      screenshotCam.radius = radius;
     } else if (boundingInfo) {
       // zoom out to have full scene in view if requested by `autofocusScene` flag
       const distance = this._getAutofocusZoomingDistance(boundingInfo.boundingSphere, screenshotCam);
@@ -290,44 +329,90 @@ export class CameraManager {
     }
     // `cloneAlphaBetaRadius` has to be set to true, otherwise these values get adapted by setting the new target
     // this would also be the case when setting `screenshotCam.target` directly
-    if (settings?.target !== undefined) {
-      screenshotCam.setTarget(settings.target, undefined, undefined, true);
+    if (target !== undefined) {
+      screenshotCam.setTarget(target, undefined, undefined, true);
     } else if (boundingInfo) {
       screenshotCam.setTarget(boundingInfo.boundingSphere.center, undefined, undefined, true);
     }
 
-    // don't expose internal props of `IScreenshotSize` in the API (yet), as it gets rather confusing and it shouldn't
-    // be necessary in the first place
-    // also let Babylon.js do all the fallback handling for missing properties
-    const size: IScreenshotSize = { width: settings?.width, height: settings?.height };
+    // calculate screenshot size manually as it is used for html anchor screenshot as well
+    const screenshotSize = this._getScreenshotSize(width, height);
+    const mimeType = settings?.mimeType ?? 'image/png';
+
+    const imageStr3d = await ScreenshotTools.CreateScreenshotUsingRenderTargetAsync(
+      this.viewer.engine,
+      screenshotCam,
+      { width: screenshotSize.imageWidth, height: screenshotSize.imageHeight },
+      mimeType,
+      samples,
+      antialiasing,
+      undefined,
+      renderSprites,
+      enableStencilBuffer,
+      useLayerMask,
+      quality,
+      texture => {
+        // NOTE: this doesn't work ATM, see https://github.com/BabylonJS/Babylon.js/pull/16081#issuecomment-2652861176
+        // we'll have to wait for a fix or solve the visibility in a different way (e.g. camera layer mask)
+        texture.renderList = this.viewer.scene.meshes.filter(
+          mesh => !settings?.exclude || !isNodeExcluded(mesh, settings.exclude)
+        );
+      }
+    );
 
-    // for some reason the `customizeTexture` property is not exposed in the async version of this function, therefore
-    // we create the promise here manually
-    const imageStr = await new Promise<string>(resolve => {
-      ScreenshotTools.CreateScreenshotUsingRenderTarget(
-        this.viewer.engine,
+    let imageStr = '';
+    const htmlAnchorKeys =
+      excludeHtmlAnchorGroups === true
+        ? []
+        : this.viewer.htmlAnchorManager.getHtmlAnchorKeys(undefined, excludeHtmlAnchorGroups, true);
+    if (htmlAnchorKeys.length) {
+      // html anchors are not included in the main screenshot, as the html elements are located outside of the canvas
+      // 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 = await this.viewer.htmlAnchorManager.createScreenshotCanvas(
+        screenshotSize,
         screenshotCam,
-        size,
-        (data: string) => resolve(data),
-        settings?.mimeType,
-        settings?.samples,
-        settings?.antialiasing,
-        settings?.fileName,
-        settings?.renderSprites,
-        settings?.enableStencilBuffer,
-        settings?.useLayerMask,
-        settings?.quality,
-        texture => {
-          texture.renderList = this.viewer.scene.meshes.filter(
-            mesh => !settings?.exclude || !isNodeExcluded(mesh, settings.exclude)
-          );
-        }
+        htmlAnchorKeys
       );
-    });
+
+      // convert the main screenshot into an image, so that it can be drawn onto a canvas as well
+      const screenshot3dImg = new Image();
+      screenshot3dImg.src = imageStr3d;
+      await new Promise(resolve => {
+        screenshot3dImg.onload = resolve;
+      });
+
+      const screenshotCombinedCanvas = document.createElement('canvas');
+      screenshotCombinedCanvas.width = screenshotSize.imageWidth;
+      screenshotCombinedCanvas.height = screenshotSize.imageHeight;
+
+      // draw main and html screenshot on a new canvas and get the base64 string from it
+      const context = screenshotCombinedCanvas.getContext('2d')!;
+      context.drawImage(screenshot3dImg, 0, 0, screenshotSize.imageWidth, screenshotSize.imageHeight);
+      context.drawImage(screenshotHtmlCanvas, 0, 0, screenshotSize.imageWidth, screenshotSize.imageHeight);
+      imageStr = screenshotCombinedCanvas.toDataURL(mimeType);
+
+      screenshotCombinedCanvas.remove();
+    } else {
+      imageStr = imageStr3d;
+    }
 
     screenshotCam.dispose();
 
-    return imageStr;
+    if (fileName) {
+      // rebuild Babylon.js default behaviour: if a file name is given, download the screenshot instead of returning the
+      // data string
+      const link = document.createElement('a');
+      link.href = imageStr;
+      link.download = fileName;
+      document.body.appendChild(link);
+      link.click();
+      document.body.removeChild(link);
+
+      return '';
+    } else {
+      return imageStr;
+    }
   }
 
   protected static _addCameraAnimationToGroup(
@@ -373,4 +458,33 @@ export class CameraManager {
 
     return distance;
   }
+
+  protected _getScreenshotSize(width?: number, height?: number): ScreenshotSize {
+    const canvas = this.viewer.canvas!;
+    const aspectRatio = canvas.width / canvas.height;
+
+    let imageWidth = 0;
+    let imageHeight = 0;
+    if (width && height) {
+      imageWidth = width;
+      imageHeight = height;
+    } else if (width && !height) {
+      imageWidth = width;
+      imageHeight = width / aspectRatio;
+    } else if (!width && height) {
+      imageWidth = height * aspectRatio;
+      imageHeight = height;
+    } else {
+      imageWidth = canvas.width;
+      imageHeight = canvas.height;
+    }
+
+    // canvas size only differs from image size if both width and height are set
+    // in this case the aspect ratio differs from the canvas aspect ratio and some parts of the canvas have to be
+    // cropped for the screenshot
+    const canvasWidth = width && height ? height * aspectRatio : imageWidth;
+    const canvasHeight = imageHeight;
+
+    return { imageWidth, imageHeight, canvasWidth, canvasHeight };
+  }
 }

package/src/manager/debug-manager.ts

@@ -20,7 +20,7 @@ import {
  * Manager for debugging functionalities
  */
 export class DebugManager {
-  protected static _BOUNDING_SPHERE_KEY = '__bounding_sphere__';
+  protected static _BOUNDING_SPHERE_KEY = '$boundingSphere';
 
   protected _axesViewer: AxesViewer | null = null;
   protected _showBoundingSphereForAutofocus: boolean = false;
@@ -91,7 +91,7 @@ The inspector can only be used in development builds.`);
   public showCoordinateSystem(node?: TransformNode, size?: number): void {
     // calculate the default size of not provided
     if (!size) {
-      const sceneBoundingInfo = this.viewer.calculateBoundingInfo();
+      const sceneBoundingInfo = this.viewer.sceneManager.calculateBoundingInfo();
       const radius = sceneBoundingInfo.boundingSphere.radius;
 
       // takes a third of the radius from scene boundingsphere
@@ -145,7 +145,7 @@ The inspector can only be used in development builds.`);
 
   /**
    * Draws a wireframe bounding sphere on the next call of {@link CameraManager.autofocusActiveCamera}.\
-   * This is usefull for checking which parts of the scene get centered.
+   * This is useful for checking which parts of the scene get centered.
    */
   public showBoundingSphereForAutofocus(): void {
     this._showBoundingSphereForAutofocus = true;