@combeenation/3d-viewer 12.4.1 → 13.0.0

package/src/manager/sceneManager.ts

@@ -0,0 +1,101 @@
+import { ArcRotateCamera, CameraManager, Color4, CubeTexture, Vector3, Viewer } from '../index';
+import { merge } from 'lodash-es';
+
+/**
+ * Settings for creating the default scene
+ */
+export type DefaultSceneSettings = {
+  backgroundColor: Color4;
+  camera: {
+    create: boolean;
+    initialPosition: {
+      alpha: number;
+      beta: number;
+      radius: number;
+      target: Vector3;
+    };
+    settings: {
+      minZ: number;
+      lowerRadiusLimit: number;
+      wheelPrecision: number;
+      panningSensibility: number;
+    };
+  };
+  environment: {
+    create: boolean;
+    url: string;
+    intensity: number;
+  };
+};
+
+/**
+ * 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.
+ *
+ * @internal
+ */
+export class SceneManager {
+  protected static _DEFAULT_SCENE_NAME = '__defaultScene__';
+
+  // default scene settings
+  // will be overwritten in the constructor
+  protected _defaultSceneSettings: DefaultSceneSettings = {
+    backgroundColor: new Color4(0, 0, 0, 0),
+    camera: {
+      create: true,
+      initialPosition: CameraManager.DEFAULT_CAMERA_POSITION,
+      settings: {
+        minZ: 0.1,
+        lowerRadiusLimit: 2,
+        wheelPrecision: 100,
+        panningSensibility: 5000,
+      },
+    },
+
+    environment: {
+      create: true,
+      url: 'https://assets.babylonjs.com/environments/environmentSpecular.env',
+      intensity: 1,
+    },
+  };
+
+  public constructor(protected viewer: Viewer, defaultSceneSettings?: DeepPartial<DefaultSceneSettings>) {
+    merge(this._defaultSceneSettings, defaultSceneSettings);
+  }
+
+  /**
+   * 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.
+   */
+  public applyDefaultSettingsToScene(): void {
+    const cameraSettings = this._defaultSceneSettings.camera;
+    const envSettings = this._defaultSceneSettings.environment;
+
+    this.viewer.scene.clearColor = this._defaultSceneSettings.backgroundColor;
+
+    // camera
+    if (cameraSettings.create) {
+      const camera = new ArcRotateCamera(
+        `${SceneManager._DEFAULT_SCENE_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;
+    }
+
+    // environment
+    if (envSettings.create) {
+      const envTexture = CubeTexture.CreateFromPrefilteredData(envSettings.url, this.viewer.scene);
+      this.viewer.scene.environmentTexture = envTexture;
+      this.viewer.scene.environmentIntensity = envSettings.intensity;
+    }
+  }
+}

package/src/manager/screenshotManager.ts

@@ -0,0 +1,59 @@
+import { IScreenshotSize, ScreenshotTools, Viewer } from '../index';
+
+// NOTE: this module will be reworked in the near future (CB-8789)
+
+export type ScreenshotSettings = {
+  /** Defaults to canvas width & height */
+  size?: IScreenshotSize;
+  /**
+   * Default `image/png`
+   *
+   * **Info regarding JPEG:** \
+   * Use mimeType `image/jpeg` (**not** `image/jpg`) when creating jpeg's. \
+   * Also ensure that the viewer scenes `clearColor` has an alpha value of `1` as jpeg's don't
+   * support transparency. Otherwise background will always be black for jpeg's.
+   */
+  mimeType?: string;
+  /** Default `1` */
+  samples?: number;
+  /** Default `false` */
+  antialiasing?: boolean;
+  /** NOTE: after update to Babylon.js V6: if file name is given, the screenshot image will be downloaded and the base64
+   * string will NOT be returned! */
+  fileName?: string;
+  /** Default `false` */
+  renderSprites?: boolean;
+};
+
+/**
+ * Manager for tasks related to screenshots
+ */
+export class ScreenshotManager {
+  /** @internal */
+  public constructor(protected viewer: Viewer) {}
+
+  /**
+   * Takes a sceenshot the the current scene.\
+   * The result is a string containing a base64 encoded image.
+   */
+  public async takeScreenshot(settings?: ScreenshotSettings): Promise<string> {
+    // in combination with a render target, we need to refresh the scene manually to get the latest view
+    this.viewer.scene.render();
+
+    const size = settings?.size ?? { width: this.viewer.canvas.clientWidth, height: this.viewer.canvas.clientHeight };
+
+    const imageStr = await ScreenshotTools.CreateScreenshotUsingRenderTargetAsync(
+      this.viewer.engine,
+      // mark as non-nullable as we wouldn't come this far if no camera is active anyway
+      this.viewer.scene.activeCamera!,
+      size,
+      settings?.mimeType,
+      settings?.samples,
+      settings?.antialiasing,
+      settings?.fileName,
+      settings?.renderSprites
+    );
+
+    return imageStr;
+  }
+}

package/src/manager/textureManager.ts

@@ -0,0 +1,32 @@
+import { BaseTexture, Viewer } from '../index';
+
+/**
+ * Manager for texture related tasks, like renaming textures that are based on Combeenation image assets.\
+ * Doesn't have any public functionalities ATM.
+ *
+ * @internal
+ */
+export class TextureManager {
+  public constructor(protected viewer: Viewer) {
+    this.viewer.scene.onNewTextureAddedObservable.add(texture => this._onTextureAdded(texture));
+  }
+
+  protected async _onTextureAdded(texture: BaseTexture): Promise<void> {
+    // Workaround:
+    // The texture object is not fully created when the "added observable" is called. E.g. the function
+    // `onLoadObservable` is not there at that point and the name is not even set.
+    // More details: https://forum.babylonjs.com/t/basetexture-whenallready-returns-too-early/34501/4
+    await new Promise(resolve => window.setTimeout(resolve, 0));
+
+    // textures based CBN image assets are hard to analyse in the inspector, since the asset url is set as name
+    // with this functionality we try to find these CBN image assets and crop the name accordingly
+    // => see CB-9558
+    const isUrl = texture.name.startsWith('https://');
+    const textureQueryString = '?name=';
+    const indexOfTextureQueryParam = texture.name.lastIndexOf(textureQueryString);
+
+    if (isUrl && indexOfTextureQueryParam > -1) {
+      texture.name = texture.name.substring(indexOfTextureQueryParam + textureQueryString.length);
+    }
+  }
+}

package/src/viewer.ts

@@ -0,0 +1,296 @@
+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,
+  ScreenshotManager,
+  TextureManager,
+  TransformNode,
+  Vector3,
+} from './index';
+import { registerCustomCbnBabylonLoaderPlugin } from './internal/cbnCustomBabylonLoaderPlugin';
+import { getIsScaledDownDevice } from './internal/deviceHelper';
+import { isNodeExcluded } from './internal/geometryHelper';
+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 _screenshotManager!: ScreenshotManager;
+  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;
+  }
+  get screenshotManager(): ScreenshotManager {
+    return this._screenshotManager;
+  }
+  /** @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._screenshotManager = new ScreenshotManager(this);
+    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();
+      }
+    });
+  }
+}

package/src/{api/classes/viewerError.ts → viewerError.ts}

@@ -17,13 +17,18 @@ type ViewerErrorData = {
  *
  * IDs here shall only include "word characters" (`/w` in RegEx) as `GetViewerErrorIdFromMsg` wouldn't work correctly
  * otherwise.
+ * @internal
  */
 export const ViewerErrorIds = {
   InvalidParameterValue: 'InvalidParameterValue',
-  UnknownParameterOption: 'UnknownParameterOption',
+  ModelNotRegistered: 'ModelNotRegistered',
+  ModelAlreadyExists: 'ModelAlreadyExists',
+  ModelIsNotAClone: 'ModelIsNotAClone',
   AssetLoadingFailed: 'AssetLoadingFailed',
+  MaterialCouldNotBeParsed: 'MaterialCouldNotBeParsed',
 };
 
+/** @internal */
 export class ViewerError extends Error {
   viewerErrorId: string;
 

package/dist/lib-cjs/api/classes/animationInterface.d.ts

@@ -1,8 +0,0 @@
-/**
- * An Interface defining the basic functionality of an animation.
- */
-export interface AnimationInterface {
-    play(): Promise<AnimationInterface>;
-    pause(): AnimationInterface;
-    kill(): AnimationInterface;
-}

package/dist/lib-cjs/api/classes/animationInterface.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=animationInterface.js.map

package/dist/lib-cjs/api/classes/animationInterface.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"animationInterface.js","sourceRoot":"","sources":["../../../../src/api/classes/animationInterface.ts"],"names":[],"mappings":""}

package/dist/lib-cjs/api/classes/dottedPath.d.ts

@@ -1,79 +0,0 @@
-export declare class DottedPath {
-    static DELIMITER: string;
-    static SAFE_CHAR: string;
-    parts: string[];
-    /**
-     * Magic factory function that creates a DottedPath based on the argument type.
-     */
-    static create(dottedPath?: DottedPathArgument): DottedPath;
-    /**
-     * Creates a DottedPath from a string.
-     * Allows patterns with unsafe characters wrapped in apostrophes or quotes.
-     * E.g. "part1.part2.'part.3'.part_4"
-     */
-    static createFromPath(path: string): DottedPath;
-    /**
-     * Creates a DottedPath from a string list.
-     */
-    static createFromParts(parts: string[]): DottedPath;
-    /**
-     * Creates an empty DottedPath.
-     */
-    static createEmpty(): DottedPath;
-    /**
-     * Sanitizes given part: replaces all characters like {@link DottedPath.DELIMITER}
-     * with a "safe" character like {@link DottedPath.SAFE_CHAR}.
-     * (i) Does not trim whitespace.
-     */
-    static sanitizePart(part: string): string;
-    /**
-     * Constructor
-     */
-    private constructor();
-    /**
-     * The path.
-     * (i) Does not return an empty dot for no path.
-     */
-    get path(): string;
-    /**
-     * The first part.
-     */
-    get firstPart(): string | null;
-    /**
-     * The last part.
-     */
-    get lastPart(): string | null;
-    /**
-     * Gets the tokens to each leaf of the DottedPath tree.
-     * E.g. "part1.part2.part_3" will return an array like
-     *      ["part1", "part1.part2", "part1.part2.part_3"]
-     */
-    get leafTokens(): string[];
-    /**
-     * Removes the first part and returns it.
-     */
-    shiftPart(): string | undefined;
-    /**
-     * Adds part to the beginning of parts list.
-     */
-    unshiftPart(part: string, duplicateCheck?: boolean): DottedPath;
-    /**
-     * Adds part to the end of parts list.
-     * (i) Does not add a part if the last char already is the delimiter or if an empty string was passed.
-     */
-    addPart(part: string, duplicateCheck?: boolean): DottedPath;
-    /**
-     * Adds multiple parts to the end of parts list.
-     */
-    addParts(parts: string[], duplicateCheck?: boolean): DottedPath;
-    /**
-     * Removes the last part and returns it.
-     */
-    popPart(): string | undefined;
-    toString(): string;
-    valueOf(): string;
-    /**
-     * Clones the DottedPath.
-     */
-    clone(): DottedPath;
-}