@combeenation/3d-viewer 14.0.0 → 14.0.1-rc1

package/src/viewer.ts

@@ -1,290 +1,290 @@
-import buildInfo from './buildinfo.json';
-import * as Index from './index';
-import {
-  BoundingInfo,
-  CameraManager,
-  DebugManager,
-  DefaultSceneSettings,
-  Engine,
-  EngineOptions,
-  EventManager,
-  GltfExportManager,
-  MaterialManager,
-  ModelManager,
-  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';
-
-/**
- * Use this to define geometry to be excluded from autofocus, GLB export, etc.
- */
-export type ExcludedGeometry = TransformNode | ParameterSubject;
-export type ExcludedGeometryList = ExcludedGeometry[];
-
-export type LimitTextureSizeConfig = {
-  size: 512 | 1024;
-  devices: 'iPhone' | 'all';
-};
-
-export type ViewerSettings = {
-  antialiasing: boolean;
-  engineOptions: EngineOptions;
-  /**
-   * Important for visual quality on iOS devices, this setting will set the hardware scaling proportional to the devices
-   * pixel ratio
-   */
-  adaptToDeviceRatio: boolean;
-  /**
-   * Possibility to limit the size of textures when getting loaded by the engine.\
-   * Activating this feature potentially saves a lot of memory and can be used to avoid crashes when loading expensive
-   * models on weaker devices.\
-   * In praxis this has been an issue with iPhones a lot, therefore it's possible to activate this feature for iPhones
-   * only as well.
-   */
-  limitTextureSize: LimitTextureSizeConfig | false;
-  /**
-   * See this forum entry for description of parallel shader compilition effect:
-   * https://forum.babylonjs.com/t/scene-flickering-when-turning-off-light/48733.\
-   * Parallel shading compilition generally improves the speed of material compilition and helps when switching
-   * materials while objects are moving (eg: animations).\
-   * Deactivating parallel shading compilition is benefitial when switching lights and materials in static scenarios.\
-   * It's activated by default due to compatibility reasons but can be overwritten with this flag.
-   */
-  useParallelShaderCompile: boolean;
-};
-
-/**
- * This is the entry point into the application.\
- * Create an instance to set up the viewer on your canvas.
- *  ```js
- * const canvas = document.getElementById('babylon-canvas');
- * const viewer = Viewer(canvas, viewerSettings, defaultSceneSettings);
- * ```
- * Use "manager" sub classes for interacting with the Babylon.js engine.
- * (e.g. `modelManager` for loading models into the scene)
- */
-export class Viewer {
-  static readonly version = buildInfo.version;
-
-  // NOTE: "non-null assertion operator" is used since these variables are not initialized in the constructor itself
-  // but in a help function (`_init`) inside the constructor
-  protected _scene!: Scene;
-
-  protected _cameraManager!: CameraManager;
-  protected _debugManager!: DebugManager;
-  protected _eventManager!: EventManager;
-  protected _gltfExportManager!: GltfExportManager;
-  protected _materialManager!: MaterialManager;
-  protected _modelManager!: ModelManager;
-  protected _parameterManager!: ParameterManager;
-  protected _sceneManager!: SceneManager;
-  protected _textureManager!: TextureManager;
-
-  // default viewer settings
-  // will be overwritten in the viewer constructor
-  protected _viewerSettings: ViewerSettings = {
-    antialiasing: true,
-    engineOptions: {
-      preserveDrawingBuffer: true,
-      stencil: true,
-      xrCompatible: false,
-    },
-    adaptToDeviceRatio: true,
-    limitTextureSize: {
-      devices: 'iPhone',
-      size: 1024,
-    },
-    useParallelShaderCompile: true,
-  };
-
-  protected _isRenderLoopPaused: boolean = false;
-
-  get scene(): Scene {
-    return this._scene;
-  }
-  get engine(): Engine {
-    return this.scene.getEngine();
-  }
-  get cameraManager(): CameraManager {
-    return this._cameraManager;
-  }
-  get debugManager(): DebugManager {
-    return this._debugManager;
-  }
-  get eventManager(): EventManager {
-    return this._eventManager;
-  }
-  get gltfExportManager(): GltfExportManager {
-    return this._gltfExportManager;
-  }
-  get materialManager(): MaterialManager {
-    return this._materialManager;
-  }
-  get modelManager(): ModelManager {
-    return this._modelManager;
-  }
-  get parameterManager(): ParameterManager {
-    return this._parameterManager;
-  }
-  /** @internal */
-  get sceneManager(): SceneManager {
-    return this._sceneManager;
-  }
-  /** @internal */
-  get textureManager(): TextureManager {
-    return this._textureManager;
-  }
-  get viewerSettings(): ViewerSettings {
-    return this._viewerSettings;
-  }
-
-  /**
-   * Returns all modules which are exported by the viewers index file.\
-   * Needed by the [Combeenation viewer control](https://docs.combeenation.com/docs/3d-viewer-control) in situations where the viewer is injected from external code.\
-   * See [Combeenation docs](https://docs.combeenation.com/docs/3d-viewer-control-with-custom-js) for more details.
-   */
-  public static getAllViewerModules(): typeof Index {
-    return Index;
-  }
-
-  /**
-   * @param viewerSettings Can be overwritten to tweak settings for the Babylon.js engine or viewer internal
-   *                       functionalities like "texture downscaling mode"
-   * @param defaultSceneSettings Can be overwritten to tweak settings for the automatically create Babylon.js scene.\
-   *                             This scene contains a camera and an environment per default.
-   */
-  public constructor(
-    public readonly canvas: HTMLCanvasElement,
-    viewerSettings?: DeepPartial<ViewerSettings>,
-    defaultSceneSettings?: DeepPartial<DefaultSceneSettings>
-  ) {
-    merge(this._viewerSettings, viewerSettings);
-    this._init(defaultSceneSettings);
-  }
-
-  /**
-   * Pause rendering can be usefull when doing internal scene processings that should not be visible to the user,
-   * e.g. cloning meshes for gltf export
-   */
-  public pauseRendering(): void {
-    this._isRenderLoopPaused = true;
-  }
-
-  /**
-   * Resume render loop when paused by {@link pauseRendering} function
-   */
-  public resumeRendering(): void {
-    this._isRenderLoopPaused = false;
-  }
-
-  /**
-   * Destroys this viewer instance and disposes Babylon.js engine and all scene content
-   */
-  public destroy(): void {
-    this.eventManager.removeAllListeners();
-    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 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 excluded meshes
-        const isExcluded = excludeGeometry ? isNodeExcluded(mesh, excludeGeometry) : false;
-        return isEnabled && hasValidBBoxInfo && !hasInfiniteDistance && !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
-   */
-  protected _init(defaultSceneSettings?: DeepPartial<DefaultSceneSettings>): void {
-    // we use a custom plugin for ".babylon" files to be able to lazy load materials that were cropped by the CBN
-    // asset manager
-    registerCustomCbnBabylonLoaderPlugin();
-
-    const engine = new Engine(
-      this.canvas,
-      this._viewerSettings.antialiasing,
-      cloneDeep(this._viewerSettings.engineOptions),
-      this._viewerSettings.adaptToDeviceRatio
-    );
-
-    const isScaledDownDevice = getIsScaledDownDevice(this._viewerSettings.limitTextureSize);
-    if (this._viewerSettings.limitTextureSize && isScaledDownDevice) {
-      engine.getCaps().maxTextureSize = this._viewerSettings.limitTextureSize.size;
-    }
-
-    if (this._viewerSettings.useParallelShaderCompile === false) {
-      engine.getCaps().parallelShaderCompile = undefined;
-    }
-
-    this._scene = new Scene(engine);
-
-    // NOTE: order of manage seems to be a bit counter intuitive as it's sorted alphabetically
-    // semantically one would start with scene manager, etc...
-    // still this is a good test as the order of manager constructors should not matter
-    this._cameraManager = new CameraManager(this);
-    this._debugManager = new DebugManager(this);
-    this._eventManager = new EventManager(this);
-    this._gltfExportManager = new GltfExportManager(this);
-    this._materialManager = new MaterialManager(this);
-    this._modelManager = new ModelManager(this);
-    this._parameterManager = new ParameterManager(this);
-    this._sceneManager = new SceneManager(this, defaultSceneSettings);
-    this._textureManager = new TextureManager(this);
-
-    // creates black cube
-    // this model is not based on an URL and can be targeted by the Combeenation backend as fallback model
-    this._modelManager.createFallbackModel();
-
-    // NOTE: ATM creating the default scene required, as otherwise no camera would be available and the first render
-    // call would already throw
-    this._sceneManager.applyDefaultSettingsToScene();
-
-    this._debugManager.registerAutofocusStartListener();
-
-    engine.runRenderLoop(() => {
-      if (!this._isRenderLoopPaused) {
-        this.scene.render();
-      }
-    });
-  }
-}
+import buildInfo from './buildinfo.json';
+import * as Index from './index';
+import {
+  BoundingInfo,
+  CameraManager,
+  DebugManager,
+  DefaultSceneSettings,
+  Engine,
+  EngineOptions,
+  EventManager,
+  GltfExportManager,
+  MaterialManager,
+  ModelManager,
+  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';
+
+/**
+ * Use this to define geometry to be excluded from autofocus, GLB export, etc.
+ */
+export type ExcludedGeometry = TransformNode | ParameterSubject;
+export type ExcludedGeometryList = ExcludedGeometry[];
+
+export type LimitTextureSizeConfig = {
+  size: 512 | 1024;
+  devices: 'iPhone' | 'all';
+};
+
+export type ViewerSettings = {
+  antialiasing: boolean;
+  engineOptions: EngineOptions;
+  /**
+   * Important for visual quality on iOS devices, this setting will set the hardware scaling proportional to the devices
+   * pixel ratio
+   */
+  adaptToDeviceRatio: boolean;
+  /**
+   * Possibility to limit the size of textures when getting loaded by the engine.\
+   * Activating this feature potentially saves a lot of memory and can be used to avoid crashes when loading expensive
+   * models on weaker devices.\
+   * In praxis this has been an issue with iPhones a lot, therefore it's possible to activate this feature for iPhones
+   * only as well.
+   */
+  limitTextureSize: LimitTextureSizeConfig | false;
+  /**
+   * See this forum entry for description of parallel shader compilition effect:
+   * https://forum.babylonjs.com/t/scene-flickering-when-turning-off-light/48733.\
+   * Parallel shading compilition generally improves the speed of material compilition and helps when switching
+   * materials while objects are moving (eg: animations).\
+   * Deactivating parallel shading compilition is benefitial when switching lights and materials in static scenarios.\
+   * It's activated by default due to compatibility reasons but can be overwritten with this flag.
+   */
+  useParallelShaderCompile: boolean;
+};
+
+/**
+ * This is the entry point into the application.\
+ * Create an instance to set up the viewer on your canvas.
+ *  ```js
+ * const canvas = document.getElementById('babylon-canvas');
+ * const viewer = Viewer(canvas, viewerSettings, defaultSceneSettings);
+ * ```
+ * Use "manager" sub classes for interacting with the Babylon.js engine.
+ * (e.g. `modelManager` for loading models into the scene)
+ */
+export class Viewer {
+  static readonly version = buildInfo.version;
+
+  // NOTE: "non-null assertion operator" is used since these variables are not initialized in the constructor itself
+  // but in a help function (`_init`) inside the constructor
+  protected _scene!: Scene;
+
+  protected _cameraManager!: CameraManager;
+  protected _debugManager!: DebugManager;
+  protected _eventManager!: EventManager;
+  protected _gltfExportManager!: GltfExportManager;
+  protected _materialManager!: MaterialManager;
+  protected _modelManager!: ModelManager;
+  protected _parameterManager!: ParameterManager;
+  protected _sceneManager!: SceneManager;
+  protected _textureManager!: TextureManager;
+
+  // default viewer settings
+  // will be overwritten in the viewer constructor
+  protected _viewerSettings: ViewerSettings = {
+    antialiasing: true,
+    engineOptions: {
+      preserveDrawingBuffer: true,
+      stencil: true,
+      xrCompatible: false,
+    },
+    adaptToDeviceRatio: true,
+    limitTextureSize: {
+      devices: 'iPhone',
+      size: 1024,
+    },
+    useParallelShaderCompile: true,
+  };
+
+  protected _isRenderLoopPaused: boolean = false;
+
+  get scene(): Scene {
+    return this._scene;
+  }
+  get engine(): Engine {
+    return this.scene.getEngine();
+  }
+  get cameraManager(): CameraManager {
+    return this._cameraManager;
+  }
+  get debugManager(): DebugManager {
+    return this._debugManager;
+  }
+  get eventManager(): EventManager {
+    return this._eventManager;
+  }
+  get gltfExportManager(): GltfExportManager {
+    return this._gltfExportManager;
+  }
+  get materialManager(): MaterialManager {
+    return this._materialManager;
+  }
+  get modelManager(): ModelManager {
+    return this._modelManager;
+  }
+  get parameterManager(): ParameterManager {
+    return this._parameterManager;
+  }
+  /** @internal */
+  get sceneManager(): SceneManager {
+    return this._sceneManager;
+  }
+  /** @internal */
+  get textureManager(): TextureManager {
+    return this._textureManager;
+  }
+  get viewerSettings(): ViewerSettings {
+    return this._viewerSettings;
+  }
+
+  /**
+   * Returns all modules which are exported by the viewers index file.\
+   * Needed by the [Combeenation viewer control](https://docs.combeenation.com/docs/3d-viewer-control) in situations where the viewer is injected from external code.\
+   * See [Combeenation docs](https://docs.combeenation.com/docs/3d-viewer-control-with-custom-js) for more details.
+   */
+  public static getAllViewerModules(): typeof Index {
+    return Index;
+  }
+
+  /**
+   * @param viewerSettings Can be overwritten to tweak settings for the Babylon.js engine or viewer internal
+   *                       functionalities like "texture downscaling mode"
+   * @param defaultSceneSettings Can be overwritten to tweak settings for the automatically create Babylon.js scene.\
+   *                             This scene contains a camera and an environment per default.
+   */
+  public constructor(
+    public readonly canvas: HTMLCanvasElement,
+    viewerSettings?: DeepPartial<ViewerSettings>,
+    defaultSceneSettings?: DeepPartial<DefaultSceneSettings>
+  ) {
+    merge(this._viewerSettings, viewerSettings);
+    this._init(defaultSceneSettings);
+  }
+
+  /**
+   * Pause rendering can be usefull when doing internal scene processings that should not be visible to the user,
+   * e.g. cloning meshes for gltf export
+   */
+  public pauseRendering(): void {
+    this._isRenderLoopPaused = true;
+  }
+
+  /**
+   * Resume render loop when paused by {@link pauseRendering} function
+   */
+  public resumeRendering(): void {
+    this._isRenderLoopPaused = false;
+  }
+
+  /**
+   * Destroys this viewer instance and disposes Babylon.js engine and all scene content
+   */
+  public destroy(): void {
+    this.eventManager.removeAllListeners();
+    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 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 excluded meshes
+        const isExcluded = excludeGeometry ? isNodeExcluded(mesh, excludeGeometry) : false;
+        return isEnabled && hasValidBBoxInfo && !hasInfiniteDistance && !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
+   */
+  protected _init(defaultSceneSettings?: DeepPartial<DefaultSceneSettings>): void {
+    // we use a custom plugin for ".babylon" files to be able to lazy load materials that were cropped by the CBN
+    // asset manager
+    registerCustomCbnBabylonLoaderPlugin();
+
+    const engine = new Engine(
+      this.canvas,
+      this._viewerSettings.antialiasing,
+      cloneDeep(this._viewerSettings.engineOptions),
+      this._viewerSettings.adaptToDeviceRatio
+    );
+
+    const isScaledDownDevice = getIsScaledDownDevice(this._viewerSettings.limitTextureSize);
+    if (this._viewerSettings.limitTextureSize && isScaledDownDevice) {
+      engine.getCaps().maxTextureSize = this._viewerSettings.limitTextureSize.size;
+    }
+
+    if (this._viewerSettings.useParallelShaderCompile === false) {
+      engine.getCaps().parallelShaderCompile = undefined;
+    }
+
+    this._scene = new Scene(engine);
+
+    // NOTE: order of manage seems to be a bit counter intuitive as it's sorted alphabetically
+    // semantically one would start with scene manager, etc...
+    // still this is a good test as the order of manager constructors should not matter
+    this._cameraManager = new CameraManager(this);
+    this._debugManager = new DebugManager(this);
+    this._eventManager = new EventManager(this);
+    this._gltfExportManager = new GltfExportManager(this);
+    this._materialManager = new MaterialManager(this);
+    this._modelManager = new ModelManager(this);
+    this._parameterManager = new ParameterManager(this);
+    this._sceneManager = new SceneManager(this, defaultSceneSettings);
+    this._textureManager = new TextureManager(this);
+
+    // creates black cube
+    // this model is not based on an URL and can be targeted by the Combeenation backend as fallback model
+    this._modelManager.createFallbackModel();
+
+    // NOTE: ATM creating the default scene required, as otherwise no camera would be available and the first render
+    // call would already throw
+    this._sceneManager.applyDefaultSettingsToScene();
+
+    this._debugManager.registerAutofocusStartListener();
+
+    engine.runRenderLoop(() => {
+      if (!this._isRenderLoopPaused) {
+        this.scene.render();
+      }
+    });
+  }
+}