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

package/src/manager/camera-manager.ts

@@ -1,236 +1,365 @@
-import {
-  Animation,
-  AnimationGroup,
-  ArcRotateCamera,
-  ExcludedGeometryList,
-  Vector3,
-  Viewer,
-  ViewerEvent,
-} from '../index';
-
-export type CameraPosition = {
-  alpha: number;
-  beta: number;
-  radius: number;
-  target: Vector3;
-};
-
-export type AutofocusSettings = {
-  /** Can be used to customize the margins shown around the 3d model. Defaults to 1. */
-  radiusFactor?: number;
-  adjustWheelPrecision?: boolean;
-  adjustPanningSensibility?: boolean;
-  adjustPinchPrecision?: boolean;
-  /** Desired horizontal camera angle, this won't be overwritten by the autofocus function */
-  alpha?: number;
-  /** Desired vertical camera angle, this won't be overwritten by the autofocus function */
-  beta?: number;
-  /** Optional list of geometry to be excluded from consideration */
-  exclude?: ExcludedGeometryList;
-  durationMs?: number;
-};
-
-/**
- * Manager for camera related tasks
- */
-export class CameraManager {
-  public static readonly CAMERA_ANIMATION_NAME = '__cameraAnimation__';
-
-  /** @internal */
-  public static readonly DEFAULT_CAMERA_POSITION: CameraPosition = {
-    alpha: (45 * Math.PI) / 180,
-    beta: (75 * Math.PI) / 180,
-    radius: 1,
-    target: new Vector3(0, 0, 0),
-  };
-
-  protected static readonly _AUTOFOCUS_CONSTANTS = {
-    minZ: 100,
-    wheelPrecision: 100,
-    panningSensibility: 2500,
-    pinchPrecision: 200,
-  };
-
-  protected static readonly _DEFAULT_AUTOFOCUS_RADIUS_FACTOR = 1;
-  protected static readonly _DEFAULT_CAM_SPEED_MS = 250;
-
-  /** @internal */
-  public constructor(protected viewer: Viewer) {}
-
-  /**
-   * Focuses the camera to see every visible mesh in scene and tries to optimize wheel precision and panning
-   */
-  public async autofocusActiveCamera(settings?: AutofocusSettings): Promise<void> {
-    const activeCamera = this.viewer.scene.activeCamera;
-
-    if (!(activeCamera instanceof ArcRotateCamera)) {
-      throw new Error(`Camera type "${activeCamera?.getClassName()}" is not implemented for "autofocusActiveCamera".`);
-    }
-
-    // get bounding box of all visible meshes, this is the base for the autofocus algorithm
-    const boundingInfo = this.viewer.calculateBoundingInfo(settings?.exclude);
-    // optionally show bounding sphere for debugging purpose
-    this.viewer.eventManager.fireEvent(ViewerEvent.AutofocusStart, boundingInfo.boundingSphere);
-
-    const radius = boundingInfo.boundingSphere.radius;
-    const center = boundingInfo.boundingSphere.center;
-
-    // set lower radius limit on edge of bounding sphere to make sure that we can't dive into the meshes
-    activeCamera.lowerRadiusLimit = radius;
-
-    // additional settings
-    // constants for division are taken directly from Babylon.js repository
-    activeCamera.minZ = Math.min(radius / CameraManager._AUTOFOCUS_CONSTANTS.minZ, 1);
-    if (settings?.adjustWheelPrecision !== false) {
-      activeCamera.wheelPrecision = CameraManager._AUTOFOCUS_CONSTANTS.wheelPrecision / radius;
-    }
-    if (settings?.adjustPanningSensibility !== false) {
-      activeCamera.panningSensibility = CameraManager._AUTOFOCUS_CONSTANTS.panningSensibility / radius;
-    }
-    if (settings?.adjustPinchPrecision !== false) {
-      activeCamera.pinchPrecision = CameraManager._AUTOFOCUS_CONSTANTS.pinchPrecision / radius;
-    }
-
-    const radiusFactor = settings?.radiusFactor ?? CameraManager._DEFAULT_AUTOFOCUS_RADIUS_FACTOR;
-    const alpha = settings?.alpha ?? CameraManager.DEFAULT_CAMERA_POSITION.alpha;
-    const beta = settings?.beta ?? CameraManager.DEFAULT_CAMERA_POSITION.beta;
-
-    // calculation is taken from Babylon.js repository, which on their side took it from this SO post:
-    // http://stackoverflow.com/questions/2866350/move-camera-to-fit-3d-scene
-    // there's a good sketch which explains the calculation quite a bit
-    const aspectRatio = this.viewer.engine.getAspectRatio(activeCamera);
-    const frustumSlopeY = Math.tan(activeCamera.fov / 2);
-    const frustumSlopeX = frustumSlopeY * aspectRatio;
-
-    const distanceForHorizontalFrustum = radius * Math.sqrt(1 + 1 / (frustumSlopeX * frustumSlopeX));
-    const distanceForVerticalFrustum = radius * Math.sqrt(1 + 1 / (frustumSlopeY * frustumSlopeY));
-    const distance = Math.max(distanceForHorizontalFrustum, distanceForVerticalFrustum);
-
-    const newCameraPosition: CameraPosition = {
-      alpha: alpha,
-      beta: beta,
-      radius: distance * radiusFactor,
-      target: center,
-    };
-
-    await this.moveActiveCameraTo(newCameraPosition, settings?.durationMs);
-  }
-
-  /**
-   * Moves the active camera smoothly to certain position
-   *
-   * @param durationMs defaults to 250ms if unset, use 0 for instant movement
-   */
-  public async moveActiveCameraTo(
-    position: CameraPosition,
-    durationMs = CameraManager._DEFAULT_CAM_SPEED_MS
-  ): Promise<void> {
-    const activeCamera = this.viewer.scene.activeCamera;
-
-    if (!(activeCamera instanceof ArcRotateCamera)) {
-      throw new Error(`Camera type "${activeCamera?.getClassName()}" is not implemented yet for "moveActiveCameraTo".`);
-    }
-
-    if (durationMs === 0) {
-      // instant movement without animation
-      activeCamera.alpha = position.alpha ?? activeCamera.alpha;
-      activeCamera.beta = position.beta ?? activeCamera.beta;
-      activeCamera.radius = position.radius ?? activeCamera.radius;
-      activeCamera.target = position.target ?? activeCamera.target;
-    }
-
-    const framesPerSec = 100;
-    const animationGroup = new AnimationGroup(CameraManager.CAMERA_ANIMATION_NAME, this.viewer.scene);
-
-    if (position.alpha !== undefined) {
-      // transform the target's alpha value into the same turn as the current camera position to avoid movements
-      // > 360 degrees
-      const alphaGap = activeCamera.alpha - position.alpha;
-      const cntTurns = Math.round(alphaGap / (2 * Math.PI));
-      const targetAlpha = position.alpha + 2 * Math.PI * cntTurns;
-
-      CameraManager._addCameraAnimationToGroup(
-        'alpha',
-        activeCamera.alpha,
-        targetAlpha,
-        framesPerSec,
-        Animation.ANIMATIONTYPE_FLOAT,
-        animationGroup,
-        activeCamera
-      );
-    }
-    if (position.beta !== undefined) {
-      CameraManager._addCameraAnimationToGroup(
-        'beta',
-        activeCamera.beta,
-        position.beta,
-        framesPerSec,
-        Animation.ANIMATIONTYPE_FLOAT,
-        animationGroup,
-        activeCamera
-      );
-    }
-    if (position.radius !== undefined) {
-      CameraManager._addCameraAnimationToGroup(
-        'radius',
-        activeCamera.radius,
-        position.radius,
-        framesPerSec,
-        Animation.ANIMATIONTYPE_FLOAT,
-        animationGroup,
-        activeCamera
-      );
-    }
-    if (position.target !== undefined) {
-      CameraManager._addCameraAnimationToGroup(
-        'target',
-        activeCamera.target,
-        position.target,
-        framesPerSec,
-        Animation.ANIMATIONTYPE_VECTOR3,
-        animationGroup,
-        activeCamera
-      );
-    }
-
-    // animation is created for 1 second (100 frames), adjust speed ratio according to desired movement time
-    const speedRatio = 1000 / durationMs;
-
-    return new Promise<void>(resolve => {
-      animationGroup.onAnimationGroupEndObservable.addOnce(() => {
-        animationGroup.dispose();
-        resolve();
-      });
-      animationGroup.start(false, speedRatio, 0, 100);
-    });
-  }
-
-  protected static _addCameraAnimationToGroup(
-    targetProperty: string,
-    from: number | Vector3,
-    to: number | Vector3,
-    framesPerSec: number,
-    dataType: number,
-    animationGroup: AnimationGroup,
-    activeCamera: ArcRotateCamera
-  ): void {
-    const alphaAnimation = new Animation(
-      targetProperty,
-      targetProperty,
-      framesPerSec,
-      dataType,
-      Animation.ANIMATIONLOOPMODE_CONSTANT
-    );
-    alphaAnimation.setKeys([
-      {
-        frame: 0,
-        value: from,
-      },
-      {
-        frame: 100,
-        value: to,
-      },
-    ]);
-    animationGroup.addTargetedAnimation(alphaAnimation, activeCamera);
-  }
-}
+import {
+  Animation,
+  AnimationGroup,
+  ArcRotateCamera,
+  BoundingSphere,
+  ExcludedGeometryList,
+  IScreenshotSize,
+  ScreenshotTools,
+  Vector3,
+  Viewer,
+  ViewerEvent,
+} from '../index';
+import { isNodeExcluded } from '../internal/geometry-helper';
+
+export type CameraPosition = {
+  alpha: number;
+  beta: number;
+  radius: number;
+  target: Vector3;
+};
+
+export type AutofocusSettings = {
+  /** Can be used to customize the margins shown around the 3d model. Defaults to 1. */
+  radiusFactor?: number;
+  adjustWheelPrecision?: boolean;
+  adjustPanningSensibility?: boolean;
+  adjustPinchPrecision?: boolean;
+  /** Desired horizontal camera angle, this won't be overwritten by the autofocus function */
+  alpha?: number;
+  /** Desired vertical camera angle, this won't be overwritten by the autofocus function */
+  beta?: number;
+  /** Optional list of geometry to be excluded from consideration */
+  exclude?: ExcludedGeometryList;
+  durationMs?: number;
+};
+
+export type ScreenshotSettings = {
+  /** Width of the final screenshot image, defaults to canvas width */
+  width?: number;
+  /** Height of the final screenshot image, defaults to canvas height */
+  height?: number;
+  /** Camera alpha angle used for the screenshot, defaults to alpha angle of currently active camera */
+  alpha?: number;
+  /** Camera beta angle used for the screenshot, defaults to beta angle of currently active camera */
+  beta?: number;
+  /**
+   * Camera radius used for the screenshot, default value depends on `autofocusScene` flag:
+   * - `true`: radius is calculated automatically so that the whole current scene content is visible
+   * - `false`: radius of currently active camera is used
+   */
+  radius?: number;
+  /**
+   * Camera target used for the screenshot, default value depends on `autofocusScene` flag:
+   * - `true`:  center of the current scene content is set as camera target
+   * - `false`: target of currently active camera is used
+   */
+  target?: Vector3;
+  /** Used to scale the calculated radius if `radius` property is not set and `autofocusScene` mode is active */
+  radiusFactor?: number;
+  /** Can be used to automatically calculate camera `radius` and `target`, if these 2 settings are not defined
+   * explicitely */
+  autofocusScene?: boolean;
+  /** Optional list of geometry to be excluded from consideration */
+  exclude?: ExcludedGeometryList;
+  /**
+   * "MIME type" of the returned screenshot image, defaults to `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;
+  /** If file name is given, the screenshot image will be downloaded and the base64 string will NOT be returned! */
+  fileName?: string;
+  /** Expert settings to tweak the screenshot image, see [Babylon.js](https://doc.babylonjs.com/typedoc/functions/BABYLON.CreateScreenshotUsingRenderTarget) docs for further information */
+  samples?: number;
+  /** Expert settings to tweak the screenshot image, see [Babylon.js](https://doc.babylonjs.com/typedoc/functions/BABYLON.CreateScreenshotUsingRenderTarget) docs for further information */
+  antialiasing?: boolean;
+  /** Expert settings to tweak the screenshot image, see [Babylon.js](https://doc.babylonjs.com/typedoc/functions/BABYLON.CreateScreenshotUsingRenderTarget) docs for further information */
+  renderSprites?: boolean;
+  /** Expert settings to tweak the screenshot image, see [Babylon.js](https://doc.babylonjs.com/typedoc/functions/BABYLON.CreateScreenshotUsingRenderTarget) docs for further information */
+  enableStencilBuffer?: boolean;
+  /** Expert settings to tweak the screenshot image, see [Babylon.js](https://doc.babylonjs.com/typedoc/functions/BABYLON.CreateScreenshotUsingRenderTarget) docs for further information */
+  useLayerMask?: boolean;
+  /** Expert settings to tweak the screenshot image, see [Babylon.js](https://doc.babylonjs.com/typedoc/functions/BABYLON.CreateScreenshotUsingRenderTarget) docs for further information */
+  quality?: number;
+};
+
+/**
+ * Manager for camera related tasks
+ */
+export class CameraManager {
+  public static readonly CAMERA_ANIMATION_NAME = '__cameraAnimation__';
+
+  /** @internal */
+  public static readonly DEFAULT_CAMERA_POSITION: CameraPosition = {
+    alpha: (45 * Math.PI) / 180,
+    beta: (75 * Math.PI) / 180,
+    radius: 1,
+    target: new Vector3(0, 0, 0),
+  };
+
+  protected static readonly _AUTOFOCUS_CONSTANTS = {
+    minZ: 100,
+    wheelPrecision: 100,
+    panningSensibility: 2500,
+    pinchPrecision: 200,
+  };
+
+  protected static readonly _DEFAULT_AUTOFOCUS_RADIUS_FACTOR = 1;
+  protected static readonly _DEFAULT_CAM_SPEED_MS = 250;
+  protected static readonly _SCREENSHOT_CAMERA_NAME = '__screenshotCamera__';
+
+  /** @internal */
+  public constructor(protected viewer: Viewer) {}
+
+  /**
+   * Focuses the camera to see every visible mesh in scene and tries to optimize wheel precision and panning
+   */
+  public async autofocusActiveCamera(settings?: AutofocusSettings): Promise<void> {
+    const activeCamera = this.viewer.scene.activeCamera;
+
+    if (!(activeCamera instanceof ArcRotateCamera)) {
+      throw new Error(`Camera type "${activeCamera?.getClassName()}" is not implemented for "autofocusActiveCamera".`);
+    }
+
+    // get bounding box of all visible meshes, this is the base for the autofocus algorithm
+    const boundingInfo = this.viewer.calculateBoundingInfo(settings?.exclude);
+    // optionally show bounding sphere for debugging purpose
+    this.viewer.eventManager.fireEvent(ViewerEvent.AutofocusStart, boundingInfo.boundingSphere);
+
+    const distance = this._getAutofocusZoomingDistance(boundingInfo.boundingSphere, activeCamera);
+    const radius = boundingInfo.boundingSphere.radius;
+    const center = boundingInfo.boundingSphere.center;
+
+    // set lower radius limit on edge of bounding sphere to make sure that we can't dive into the meshes
+    activeCamera.lowerRadiusLimit = radius;
+
+    // additional settings
+    // constants for division are taken directly from Babylon.js repository
+    activeCamera.minZ = Math.min(radius / CameraManager._AUTOFOCUS_CONSTANTS.minZ, 1);
+    if (settings?.adjustWheelPrecision !== false) {
+      activeCamera.wheelPrecision = CameraManager._AUTOFOCUS_CONSTANTS.wheelPrecision / radius;
+    }
+    if (settings?.adjustPanningSensibility !== false) {
+      activeCamera.panningSensibility = CameraManager._AUTOFOCUS_CONSTANTS.panningSensibility / radius;
+    }
+    if (settings?.adjustPinchPrecision !== false) {
+      activeCamera.pinchPrecision = CameraManager._AUTOFOCUS_CONSTANTS.pinchPrecision / radius;
+    }
+
+    const radiusFactor = settings?.radiusFactor ?? CameraManager._DEFAULT_AUTOFOCUS_RADIUS_FACTOR;
+    const alpha = settings?.alpha ?? CameraManager.DEFAULT_CAMERA_POSITION.alpha;
+    const beta = settings?.beta ?? CameraManager.DEFAULT_CAMERA_POSITION.beta;
+
+    const newCameraPosition: CameraPosition = {
+      alpha: alpha,
+      beta: beta,
+      radius: distance * radiusFactor,
+      target: center,
+    };
+
+    await this.moveActiveCameraTo(newCameraPosition, settings?.durationMs);
+  }
+
+  /**
+   * Moves the active camera smoothly to certain position
+   *
+   * @param durationMs defaults to 250ms if unset, use 0 for instant movement
+   */
+  public async moveActiveCameraTo(
+    position: CameraPosition,
+    durationMs = CameraManager._DEFAULT_CAM_SPEED_MS
+  ): Promise<void> {
+    const activeCamera = this.viewer.scene.activeCamera;
+
+    if (!(activeCamera instanceof ArcRotateCamera)) {
+      throw new Error(`Camera type "${activeCamera?.getClassName()}" is not implemented yet for "moveActiveCameraTo".`);
+    }
+
+    if (durationMs === 0) {
+      // instant movement without animation
+      activeCamera.alpha = position.alpha ?? activeCamera.alpha;
+      activeCamera.beta = position.beta ?? activeCamera.beta;
+      activeCamera.radius = position.radius ?? activeCamera.radius;
+      activeCamera.target = position.target ?? activeCamera.target;
+    }
+
+    const framesPerSec = 100;
+    const animationGroup = new AnimationGroup(CameraManager.CAMERA_ANIMATION_NAME, this.viewer.scene);
+
+    if (position.alpha !== undefined) {
+      // transform the target's alpha value into the same turn as the current camera position to avoid movements
+      // > 360 degrees
+      const alphaGap = activeCamera.alpha - position.alpha;
+      const cntTurns = Math.round(alphaGap / (2 * Math.PI));
+      const targetAlpha = position.alpha + 2 * Math.PI * cntTurns;
+
+      CameraManager._addCameraAnimationToGroup(
+        'alpha',
+        activeCamera.alpha,
+        targetAlpha,
+        framesPerSec,
+        Animation.ANIMATIONTYPE_FLOAT,
+        animationGroup,
+        activeCamera
+      );
+    }
+    if (position.beta !== undefined) {
+      CameraManager._addCameraAnimationToGroup(
+        'beta',
+        activeCamera.beta,
+        position.beta,
+        framesPerSec,
+        Animation.ANIMATIONTYPE_FLOAT,
+        animationGroup,
+        activeCamera
+      );
+    }
+    if (position.radius !== undefined) {
+      CameraManager._addCameraAnimationToGroup(
+        'radius',
+        activeCamera.radius,
+        position.radius,
+        framesPerSec,
+        Animation.ANIMATIONTYPE_FLOAT,
+        animationGroup,
+        activeCamera
+      );
+    }
+    if (position.target !== undefined) {
+      CameraManager._addCameraAnimationToGroup(
+        'target',
+        activeCamera.target,
+        position.target,
+        framesPerSec,
+        Animation.ANIMATIONTYPE_VECTOR3,
+        animationGroup,
+        activeCamera
+      );
+    }
+
+    // animation is created for 1 second (100 frames), adjust speed ratio according to desired movement time
+    const speedRatio = 1000 / durationMs;
+
+    return new Promise<void>(resolve => {
+      animationGroup.onAnimationGroupEndObservable.addOnce(() => {
+        animationGroup.dispose();
+        resolve();
+      });
+      animationGroup.start(false, speedRatio, 0, 100);
+    });
+  }
+
+  /**
+   * Takes a sceenshot the the current scene.\
+   * The result is a string containing a base64 encoded image.
+   */
+  public async createScreenshot(settings?: ScreenshotSettings): Promise<string> {
+    const screenshotCam = this.viewer.scene.activeCamera?.clone(
+      CameraManager._SCREENSHOT_CAMERA_NAME
+    ) as ArcRotateCamera;
+    const boundingInfo = settings?.autofocusScene ? this.viewer.calculateBoundingInfo(settings.exclude) : undefined;
+
+    if (settings?.alpha !== undefined) {
+      screenshotCam.alpha = settings.alpha;
+    }
+    if (settings?.beta !== undefined) {
+      screenshotCam.beta = settings.beta;
+    }
+    if (settings?.radius !== undefined) {
+      screenshotCam.radius = settings.radius;
+    } else if (boundingInfo) {
+      // zoom out to have full scene in view if requested by `autofocusScene` flag
+      const distance = this._getAutofocusZoomingDistance(boundingInfo.boundingSphere, screenshotCam);
+      const radiusFactor = settings?.radiusFactor ?? 1;
+      screenshotCam.radius = distance * radiusFactor;
+    }
+    // `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);
+    } 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 };
+
+    // 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,
+        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)
+          );
+        }
+      );
+    });
+
+    screenshotCam.dispose();
+
+    return imageStr;
+  }
+
+  protected static _addCameraAnimationToGroup(
+    targetProperty: string,
+    from: number | Vector3,
+    to: number | Vector3,
+    framesPerSec: number,
+    dataType: number,
+    animationGroup: AnimationGroup,
+    activeCamera: ArcRotateCamera
+  ): void {
+    const alphaAnimation = new Animation(
+      targetProperty,
+      targetProperty,
+      framesPerSec,
+      dataType,
+      Animation.ANIMATIONLOOPMODE_CONSTANT
+    );
+    alphaAnimation.setKeys([
+      {
+        frame: 0,
+        value: from,
+      },
+      {
+        frame: 100,
+        value: to,
+      },
+    ]);
+    animationGroup.addTargetedAnimation(alphaAnimation, activeCamera);
+  }
+
+  protected _getAutofocusZoomingDistance(boundingSphere: BoundingSphere, camera: ArcRotateCamera): number {
+    // calculation is taken from Babylon.js repository, which on their side took it from this SO post:
+    // http://stackoverflow.com/questions/2866350/move-camera-to-fit-3d-scene
+    // there's a good sketch which explains the calculation quite a bit
+    const aspectRatio = this.viewer.engine.getAspectRatio(camera);
+    const frustumSlopeY = Math.tan(camera.fov / 2);
+    const frustumSlopeX = frustumSlopeY * aspectRatio;
+
+    const distanceForHorizontalFrustum = boundingSphere.radius * Math.sqrt(1 + 1 / (frustumSlopeX * frustumSlopeX));
+    const distanceForVerticalFrustum = boundingSphere.radius * Math.sqrt(1 + 1 / (frustumSlopeY * frustumSlopeY));
+    const distance = Math.max(distanceForHorizontalFrustum, distanceForVerticalFrustum);
+
+    return distance;
+  }
+}