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

package/src/manager/scene-manager.ts

@@ -1,4 +1,22 @@
-import { ArcRotateCamera, CameraManager, Color4, CubeTexture, Vector3, Viewer } from '../index';
+import {
+  AbstractMesh,
+  ArcRotateCamera,
+  AssetContainer,
+  BackgroundMaterial,
+  BoundingInfo,
+  CameraManager,
+  Color4,
+  CubeTexture,
+  ExcludedGeometryList,
+  IShadowGenerator,
+  TransformNode,
+  Vector3,
+  Viewer,
+  ViewerError,
+  ViewerErrorIds,
+} from '../index';
+import { BaseAsset, loadAsset, prepareAssetForScene } from '../internal/asset-helper';
+import { isNodeExcluded } from '../internal/geometry-helper';
 import { merge } from 'lodash-es';
 
 /**
@@ -28,15 +46,68 @@ export type DefaultSceneSettings = {
   };
 };
 
+export type SceneAssetDefinition = {
+  name: string;
+  url: string;
+};
+
+export type UpdateGroundSettings = {
+  /**
+   * Ground mesh, which will be rescaled and repositioned.\
+   * Searches for mesh with name "BackgroundPlane" if left `undefined`
+   */
+  groundMesh?: TransformNode;
+  /**
+   * Additional scaling factor for ground size, default is 5, which equals 5 times the bounding sphere diameter of the
+   * current scene
+   */
+  factor?: number;
+  /**
+   * Optional list of geometry to be excluded from scene size calculation
+   */
+  excludeGeometry?: ExcludedGeometryList;
+};
+
+export type UpdateShadowsSettings = {
+  /**
+   * Shadow generator, which should be updated.\
+   * All shadow generators will be updated, if value is left `undefined`.
+   */
+  shadowGenerators?: IShadowGenerator[];
+  /**
+   * Optional list of geometry which should not be defined as shadow caster
+   */
+  excludeCaster?: ExcludedGeometryList;
+  /**
+   * Optional list of geometry which should not be defined as shadow receiver
+   */
+  excludeReceiver?: ExcludedGeometryList;
+};
+
 /**
- * Manager for tasks related to the Babylon.js scene.\
- * This contains creating or loading (WIP: Scene Asset) scenes with certain settings for lighting, cameras and
- * appearance in genereal.
+ * Additional scene settings, which are not available in a basic `AssetContainer`.
+ * !!! IMPORTANT when adding a new property !!!
+ * Add property in implementation of `cbnCustomBabylonLoader` as well
  *
  * @internal
  */
+export type SceneAssetSettings = {
+  clearColor?: Color4;
+  environmentIntensity?: number;
+};
+
+type SceneAsset = BaseAsset & {
+  settings: SceneAssetSettings;
+};
+
+/**
+ * Manager for tasks related to the Babylon.js scene.\
+ * This contains creating or loading scenes with certain settings for lighting, cameras and appearance in genereal.
+ */
 export class SceneManager {
-  protected static _DEFAULT_SCENE_NAME = '__defaultScene__';
+  protected static _DEFAULT_SCENE_ASSET_NAME = '$default';
+  protected static _DEFAULT_GROUND_PLANE_NAME = 'BackgroundPlane';
+  protected static _DEFAULT_GROUND_SIZING_FACTOR = 5;
 
   // default scene settings
   // will be overwritten in the constructor
@@ -60,42 +131,327 @@ export class SceneManager {
     },
   };
 
+  protected _sceneAssets: { [name: string]: SceneAsset } = {};
+  protected _defaultSceneAsset: SceneAsset = {
+    name: SceneManager._DEFAULT_SCENE_ASSET_NAME,
+    url: '',
+    state: 'loaded',
+    assetContainer: new AssetContainer(),
+    settings: {},
+  };
+  protected _activeSceneAssetName: string = '';
+  protected _loadSceneAssetPromises: { [sceneAssetName: string]: Promise<void> } = {};
+  protected _setSceneAssetCallId = 0;
+
+  /** @internal */
   public constructor(protected viewer: Viewer, defaultSceneSettings?: DeepPartial<DefaultSceneSettings>) {
     merge(this._defaultSceneSettings, defaultSceneSettings);
   }
 
+  /**
+   * Register scene assets for 3d viewer, this is required for each scene asset before it can be loaded/shown.\
+   * The "viewer control" inside the Combeenation framework calls this function automatically with all assigned
+   * scene assets.
+   */
+  public registerSceneAssets(sceneAssets: SceneAssetDefinition[]): void {
+    for (const { name, url } of sceneAssets) {
+      const existingSceneAsset = this._sceneAssets[name];
+      if (existingSceneAsset) {
+        console.warn(`Scene asset "${name}" is already registered`);
+        return;
+      }
+
+      const sceneAsset: SceneAsset = {
+        name,
+        url,
+        state: 'notLoaded',
+        assetContainer: new AssetContainer(),
+        settings: {},
+      };
+      this._sceneAssets[name] = sceneAsset;
+    }
+  }
+
+  /**
+   * Set desired scene asset as active and loads the content of the associated asset container (e.g. ground mesh).\
+   * This also deactivates the currently active scene asset, as only one scene asset can be active at a time.
+   */
+  public async setSceneAsset(name: string, skipPreparation?: boolean): Promise<void> {
+    const sceneAsset = this._getSceneAsset(name);
+    if (!sceneAsset) {
+      throw new ViewerError({
+        id: ViewerErrorIds.SceneAssetNotRegistered,
+        message: `Can't set scene asset "${name}" as scene asset is not registered`,
+      });
+    }
+
+    this._setSceneAssetCallId++;
+    const curSetSceneAssetCallId = this._setSceneAssetCallId;
+
+    if (sceneAsset.state === 'notLoaded') {
+      await this._loadSceneAsset(sceneAsset);
+    } else if (sceneAsset.state === 'loading') {
+      await this._loadSceneAssetPromises[name];
+    } else if (sceneAsset.state === 'inScene') {
+      console.warn(`Scene asset ${name} is already active`);
+      return;
+    }
+
+    // a new `setSceneAsset` call has been fired
+    if (curSetSceneAssetCallId !== this._setSceneAssetCallId) {
+      return;
+    }
+
+    if (!skipPreparation) {
+      await prepareAssetForScene(sceneAsset, this.viewer);
+    }
+
+    sceneAsset.assetContainer.addToScene();
+    const firstCam = sceneAsset.assetContainer.cameras[0];
+    if (firstCam) {
+      this.viewer.scene.activeCamera = firstCam;
+      this.viewer.scene.activeCamera.attachControl(undefined, true);
+    }
+
+    if (sceneAsset.assetContainer.environmentTexture) {
+      this.viewer.scene.environmentTexture = sceneAsset.assetContainer.environmentTexture;
+    }
+    if (sceneAsset.settings.clearColor) {
+      this.viewer.scene.clearColor = sceneAsset.settings.clearColor;
+    }
+    if (sceneAsset.settings.environmentIntensity !== undefined) {
+      this.viewer.scene.environmentIntensity = sceneAsset.settings.environmentIntensity;
+    }
+
+    sceneAsset.state = 'inScene';
+
+    // now hide old scene asset
+    // it's important that this is done after setting the new one to active, as there might be a render cycle with no
+    // cameras instead
+    const activeSceneAsset = this._getSceneAsset(this._activeSceneAssetName);
+    if (activeSceneAsset) {
+      this._hideSceneAsset(activeSceneAsset);
+    }
+
+    // finally set new scene asset as active
+    this._activeSceneAssetName = name;
+  }
+
+  /**
+   * Activate default scene asset
+   */
+  public setDefaultSceneAsset(): void {
+    // NOTE: this function is not async because:
+    // - `setDefaultSceneAsset` is part of the viewers "bootstrapping" process which is synchronous
+    // - default scene asset only adjusts some setting but doesn't load anything
+    this.setSceneAsset(SceneManager._DEFAULT_SCENE_ASSET_NAME, true);
+  }
+
+  /**
+   * Loads and returns the asset container of a certain scene asset.\
+   * This can be used to access the scene asset content without having to add it to the scene.
+   */
+  public async getAssetContainerOfSceneAsset(name: string): Promise<AssetContainer> {
+    const sceneAsset = this._getSceneAsset(name);
+    if (!sceneAsset) {
+      throw new ViewerError({
+        id: ViewerErrorIds.SceneAssetNotRegistered,
+        message: `Can't get asset container of scene asset "${name}" as scene asset is not registered`,
+      });
+    }
+
+    if (sceneAsset.state === 'notLoaded') {
+      await this._loadSceneAsset(sceneAsset);
+    } else if (sceneAsset.state === 'loading') {
+      await this._loadSceneAssetPromises[sceneAsset.name];
+    }
+
+    if (sceneAsset.state !== 'inScene') {
+      await prepareAssetForScene(sceneAsset, this.viewer);
+    }
+
+    return sceneAsset.assetContainer;
+  }
+
+  /**
+   * Calculates size of the current scene.\
+   * 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 {
+    // CB-6062: workaround for BoundingBox not respecting render loop
+    this.viewer.scene.render();
+
+    const { max, min } = this.viewer.scene.meshes
+      .filter(mesh => {
+        const isEnabled = mesh.isEnabled();
+        // ignore meshes with invalid bounding infos
+        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 && !hasBackgroundMaterial && !isExcluded;
+      })
+      .reduce(
+        (accBBoxMinMax, curMesh, idx) => {
+          curMesh.refreshBoundingInfo(true, true);
+          const bBox = curMesh.getBoundingInfo().boundingBox;
+          // use the first entry in the array as default value and get the resulting maximum/minimum values
+          const max = idx === 0 ? bBox.maximumWorld : Vector3.Maximize(accBBoxMinMax.max, bBox.maximumWorld);
+          const min = idx === 0 ? bBox.minimumWorld : Vector3.Minimize(accBBoxMinMax.min, bBox.minimumWorld);
+          return { max, min };
+        },
+        { max: new Vector3(), min: new Vector3() }
+      );
+
+    const boundingInfo = new BoundingInfo(min, max);
+    return boundingInfo;
+  }
+
+  /**
+   * Adjusts position and scaling of a dedicated "ground" meshes according to the bounding sphere of the current scene
+   * content.\
+   * This function is designed to adjust the ground that is created via `scene.createDefaultEnvironment`, but any other
+   * plane mesh can be used as well.
+   */
+  public updateGround(settings?: UpdateGroundSettings): void {
+    const bboxInfo = this.calculateBoundingInfo(settings?.excludeGeometry);
+
+    const groundMesh = settings?.groundMesh ?? this.viewer.scene.getMeshByName(SceneManager._DEFAULT_GROUND_PLANE_NAME);
+    if (!groundMesh) {
+      console.warn("Can't update ground, as no ground mesh is available");
+      return;
+    }
+
+    // 2: conversion from radius to diameter
+    const factor =
+      bboxInfo.boundingSphere.radius * 2 * (settings?.factor ?? SceneManager._DEFAULT_GROUND_SIZING_FACTOR);
+    const position = bboxInfo.boundingSphere.centerWorld;
+    groundMesh.scaling = new Vector3(factor, factor, 1);
+    groundMesh.position = new Vector3(position.x, 0, position.z);
+  }
+
+  /**
+   * Assigns available meshes in scene as shadow receiver and shadow casters of dedicated shadow generators, as defined
+   * in settings
+   */
+  public updateShadows(settings?: UpdateShadowsSettings): void {
+    const shadowGenerators =
+      settings?.shadowGenerators ??
+      (this.viewer.scene.lights.map(light => light.getShadowGenerator()).filter(Boolean) as IShadowGenerator[]);
+
+    const shadowCasterMeshes: AbstractMesh[] = [];
+    this.viewer.scene.meshes.forEach(mesh => {
+      const isShadowReceiver = settings?.excludeReceiver ? !isNodeExcluded(mesh, settings.excludeReceiver) : true;
+      if (isShadowReceiver) {
+        mesh.receiveShadows = true;
+      }
+
+      // excluding background meshes like ground or walls from shadow casters is benefitial to reduce the size of the
+      // poisson filters auto shadow plane calculation, which will result in better shadow resolution
+      const hasBackgroundMaterial = mesh.material instanceof BackgroundMaterial;
+      const isShadowCaster = settings?.excludeCaster ? !isNodeExcluded(mesh, settings.excludeCaster) : true;
+      if (isShadowCaster && !hasBackgroundMaterial) {
+        shadowCasterMeshes.push(mesh);
+      }
+    });
+
+    shadowGenerators.forEach(shadowGen => {
+      const shadowMap = shadowGen.getShadowMap();
+      if (!shadowMap) {
+        return;
+      }
+
+      shadowMap.renderList = [...shadowCasterMeshes];
+      shadowGen.recreateShadowMap();
+    });
+  }
+
   /**
    * Creates a camera and minimum lighting, so that the scene is set up good enough to show content.\
    * Settings can be overwritten in the constructor.
+   *
+   * @internal
    */
   public applyDefaultSettingsToScene(): void {
     const cameraSettings = this._defaultSceneSettings.camera;
     const envSettings = this._defaultSceneSettings.environment;
 
-    this.viewer.scene.clearColor = this._defaultSceneSettings.backgroundColor;
+    // NOTE: default scene asset doesn't load anything, in this way the viewers "bootstrapping" process can remain
+    // synchronous
+    this._defaultSceneAsset = {
+      name: SceneManager._DEFAULT_SCENE_ASSET_NAME,
+      url: '',
+      state: 'loaded',
+      assetContainer: new AssetContainer(),
+      settings: {},
+    };
+
+    this._defaultSceneAsset.settings.clearColor = this._defaultSceneSettings.backgroundColor;
 
     // camera
     if (cameraSettings.create) {
       const camera = new ArcRotateCamera(
-        `${SceneManager._DEFAULT_SCENE_NAME}.camera`,
+        `${SceneManager._DEFAULT_SCENE_ASSET_NAME}.camera`,
         cameraSettings.initialPosition.alpha,
         cameraSettings.initialPosition.beta,
         cameraSettings.initialPosition.radius,
         cameraSettings.initialPosition.target,
         this.viewer.scene
       );
-      camera.attachControl(this.viewer.engine._workingCanvas, true);
       camera.minZ = cameraSettings.settings.minZ;
       camera.lowerRadiusLimit = cameraSettings.settings.lowerRadiusLimit;
       camera.wheelPrecision = cameraSettings.settings.wheelPrecision;
       camera.panningSensibility = cameraSettings.settings.panningSensibility;
+      camera.attachControl(undefined, true);
+
+      this._defaultSceneAsset.assetContainer.cameras.push(camera);
+      this.viewer.scene.removeCamera(camera);
     }
 
     // environment
     if (envSettings.create) {
       const envTexture = CubeTexture.CreateFromPrefilteredData(envSettings.url, this.viewer.scene);
-      this.viewer.scene.environmentTexture = envTexture;
-      this.viewer.scene.environmentIntensity = envSettings.intensity;
+
+      this._defaultSceneAsset.assetContainer.environmentTexture = envTexture;
+      this._defaultSceneAsset.settings.environmentIntensity = envSettings.intensity;
     }
+
+    this.setDefaultSceneAsset();
+  }
+
+  protected _getSceneAsset(name: string): SceneAsset | undefined {
+    if (name === SceneManager._DEFAULT_SCENE_ASSET_NAME) {
+      return this._defaultSceneAsset;
+    }
+
+    const sceneAsset = this._sceneAssets[name];
+    return sceneAsset;
+  }
+
+  protected async _loadSceneAsset(sceneAsset: SceneAsset): Promise<void> {
+    const loadSceneAssetPromise = async (): Promise<void> => {
+      const { sceneSettingsData } = await loadAsset(sceneAsset, this.viewer);
+
+      sceneAsset.settings = sceneSettingsData ?? {};
+
+      delete this._loadSceneAssetPromises[sceneAsset.name];
+    };
+
+    this._loadSceneAssetPromises[sceneAsset.name] = loadSceneAssetPromise();
+    return this._loadSceneAssetPromises[sceneAsset.name];
+  }
+
+  protected _hideSceneAsset(sceneAsset: SceneAsset): void {
+    sceneAsset.assetContainer.cameras.forEach(camera => camera.detachControl());
+    sceneAsset.assetContainer.removeFromScene();
+    sceneAsset.state = 'loaded';
   }
 }

package/src/viewer-error.ts

@@ -25,6 +25,7 @@ export const ViewerErrorIds = {
   ModelNotRegistered: 'ModelNotRegistered',
   ModelAlreadyExists: 'ModelAlreadyExists',
   ModelIsNotAClone: 'ModelIsNotAClone',
+  SceneAssetNotRegistered: 'SceneAssetNotRegistered',
   AssetLoadingFailed: 'AssetLoadingFailed',
   MaterialAlreadyExists: 'MaterialAlreadyExists',
   NotAClonedMaterial: 'NotAClonedMaterial',

package/src/viewer.ts

@@ -1,8 +1,7 @@
 import buildInfo from './buildinfo.json';
 import * as Index from './index';
 import {
-  BackgroundMaterial,
-  BoundingInfo,
+  AbstractEngine,
   CameraManager,
   DebugManager,
   DefaultSceneSettings,
@@ -12,17 +11,16 @@ import {
   GltfExportManager,
   MaterialManager,
   ModelManager,
+  NullEngine,
   ParameterManager,
   ParameterSubject,
   Scene,
   SceneManager,
   TextureManager,
   TransformNode,
-  Vector3,
 } from './index';
 import { registerCustomCbnBabylonLoaderPlugin } from './internal/cbn-custom-babylon-loader-plugin';
 import { getIsScaledDownDevice } from './internal/device-helper';
-import { isNodeExcluded } from './internal/geometry-helper';
 import { cloneDeep, merge } from 'lodash-es';
 
 /**
@@ -112,8 +110,8 @@ export class Viewer {
   get scene(): Scene {
     return this._scene;
   }
-  get engine(): Engine {
-    return this.scene.getEngine() as Engine;
+  get engine(): AbstractEngine {
+    return this.scene.getEngine();
   }
   get cameraManager(): CameraManager {
     return this._cameraManager;
@@ -164,7 +162,7 @@ export class Viewer {
    *                             This scene contains a camera and an environment per default.
    */
   public constructor(
-    public readonly canvas: HTMLCanvasElement,
+    public readonly canvas?: HTMLCanvasElement,
     viewerSettings?: DeepPartial<ViewerSettings>,
     defaultSceneSettings?: DeepPartial<DefaultSceneSettings>
   ) {
@@ -195,48 +193,6 @@ export class Viewer {
     this.engine.dispose();
   }
 
-  /**
-   * Calculates size of the current scene.\
-   * 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 {
-    // CB-6062: workaround for BoundingBox not respecting render loop
-    this.scene.render();
-
-    const { max, min } = this.scene.meshes
-      .filter(mesh => {
-        const isEnabled = mesh.isEnabled();
-        // ignore meshes with invalid bounding infos
-        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 && !hasBackgroundMaterial && !isExcluded;
-      })
-      .reduce(
-        (accBBoxMinMax, curMesh, idx) => {
-          curMesh.refreshBoundingInfo(true, true);
-          const bBox = curMesh.getBoundingInfo().boundingBox;
-          // use the first entry in the array as default value and get the resulting maximum/minimum values
-          const max = idx === 0 ? bBox.maximumWorld : Vector3.Maximize(accBBoxMinMax.max, bBox.maximumWorld);
-          const min = idx === 0 ? bBox.minimumWorld : Vector3.Minimize(accBBoxMinMax.min, bBox.minimumWorld);
-          return { max, min };
-        },
-        { max: new Vector3(), min: new Vector3() }
-      );
-
-    const boundingInfo = new BoundingInfo(min, max);
-    return boundingInfo;
-  }
-
   /**
    * Set up viewer (engine and scene) and initialize all managers
    */
@@ -252,12 +208,14 @@ export class Viewer {
     // - probably dimensions line handling (not implemented yet)
     TransformNode.BillboardUseParentOrientation = true;
 
-    const engine = new Engine(
-      this.canvas,
-      this._viewerSettings.antialiasing,
-      cloneDeep(this._viewerSettings.engineOptions),
-      this._viewerSettings.adaptToDeviceRatio
-    );
+    const engine: AbstractEngine = this.canvas
+      ? new Engine(
+          this.canvas,
+          this._viewerSettings.antialiasing,
+          cloneDeep(this._viewerSettings.engineOptions),
+          this._viewerSettings.adaptToDeviceRatio
+        )
+      : new NullEngine();
 
     const isScaledDownDevice = getIsScaledDownDevice(this._viewerSettings.limitTextureSize);
     if (this._viewerSettings.limitTextureSize && isScaledDownDevice) {

package/src/dev.ts

@@ -1,47 +0,0 @@
-import { Viewer } from '.';
-import {
-  afterViewerSetup,
-  createUIelements,
-  getDefaultSceneSettings,
-  getMaterial,
-  getViewerSettings,
-} from '../assets/index';
-import { mockMaterials } from '../assets/utils/mock-materials';
-import { set } from 'lodash-es';
-
-document.addEventListener('DOMContentLoaded', main);
-
-window.Cbn = {
-  Assets: {
-    async getMaterial(materialId: string): Promise<object> {
-      //! this creates a new function on the object that uses the imported function of the same name..
-      const material = await getMaterial(materialId);
-      if (material) return material;
-
-      // Fallback to random mock material
-      return mockMaterials[Math.floor(Math.random() * mockMaterials.length)];
-    },
-    assertMaterialExists(materialId: string): boolean {
-      return true;
-    },
-  },
-  utils: {
-    Viewer3dHelper: {
-      getCfgrParentDomElementForInspector(): HTMLElement | undefined {
-        // render in parent of viewer
-        return document.querySelector<HTMLElement>('display-container') ?? undefined;
-      },
-    },
-  },
-};
-
-async function main(): Promise<void> {
-  const canvas = document.getElementById('babylon-canvas') as HTMLCanvasElement;
-  const viewer = new Viewer(canvas, getViewerSettings(), getDefaultSceneSettings());
-
-  await afterViewerSetup(viewer);
-  await createUIelements(viewer);
-
-  // "Export" for console testing...
-  set(window, 'viewer', viewer);
-}