@combeenation/3d-viewer 6.1.0 → 6.2.0

package/src/api/classes/placementAnimation.ts

@@ -1,162 +1,162 @@
-import { Parameter } from '../classes/parameter';
-import { SpecStorage } from '../store/specStorage';
-import { AnimationInterface } from './animationInterface';
-import { ArcRotateCamera } from '@babylonjs/core/Cameras/arcRotateCamera';
-import { Vector3 } from '@babylonjs/core/Maths/math.vector';
-import { gsap } from 'gsap';
-import { cloneDeep, get, isString, merge, set } from 'lodash-es';
-
-/**
- * An {@link PlacementAnimation} handling `Tweens` of the `GSAP` API using configured {@link PlacementDefinition}s
- * and {@link AnimationDefinition}s. It mutates the attributes in the given {@link PlacementDefinition} with the given
- * {@link AnimationDefinition}. The latter can be anything the `GSAP` allows in its API. Please consider using the
- * API of the {@link AnimationManager} to handle instances of this class in your consuming project.
- */
-export class PlacementAnimation implements AnimationInterface {
-  protected _placementDefinition: PlacementDefinition;
-
-  protected _animationDefinition: AnimationDefinition;
-
-  protected _timeline: GSAPTimeline;
-
-  /**
-   * Constructor.
-   */
-  public constructor(
-    public readonly mutable: object,
-    protected _placement: PlacementDefinition | string,
-    protected _animation?: AnimationDefinition | string
-  ) {
-    if (isString(_placement)) {
-      const placementDefinitions = SpecStorage.get<PlacementDefinitions>('scene.placements');
-      if (!placementDefinitions) {
-        throw new Error(`No PlacementDefinitions defined in JSON structure.`);
-      }
-      const placementDefinition = placementDefinitions[_placement];
-      if (!placementDefinition) {
-        throw new Error(`PlacementDefinition "${_placement}" not defined in JSON structure.`);
-      }
-      this._placementDefinition = cloneDeep(placementDefinition);
-    } else {
-      this._placementDefinition = cloneDeep(_placement) as PlacementDefinition;
-    }
-    if (isString(_animation)) {
-      const animationDefinition = SpecStorage.get<AnimationDefinitions>('scene.animations')?.[_animation];
-      if (!animationDefinition) {
-        throw new Error(`AnimationDefinition "${_animation}" not defined in JSON structure.`);
-      }
-      this._animationDefinition = cloneDeep(animationDefinition);
-    } else {
-      this._animationDefinition = cloneDeep(_animation) as AnimationDefinition;
-    }
-
-    this.prepareAnimationDefinition();
-    // create (shallow) copy for GSAP which doesn't contain `shortestWay`,
-    // because that's not part of the original `TweenVars` input typing and therefore leads to warnings
-    const { shortestWay, ...gsapTweenVars } = this._animationDefinition;
-    this._timeline = gsap.timeline({
-      defaults: gsapTweenVars,
-      paused: true,
-    });
-
-    this.preparePlacementDefinition();
-    this.createTweens();
-  }
-
-  /**
-   * Plays all `Tweens` of this {@link PlacementAnimation}.
-   */
-  public async play(): Promise<AnimationInterface> {
-    await this._timeline.play().then();
-    return this;
-  }
-
-  /**
-   * Pause all `Tweens` of this {@link PlacementAnimation}.
-   */
-  public pause(): AnimationInterface {
-    this._timeline.pause();
-    return this;
-  }
-
-  /**
-   * Kills all `Tweens` of this {@link PlacementAnimation}.
-   */
-  public kill(): AnimationInterface {
-    this._timeline.kill();
-    return this;
-  }
-
-  /**
-   * Creates a {@link AnimationDefinition} definition if not provided in the constructor and sets some defaults.
-   * Only custom properties from {@link AnimationDefinition} are adjusted, all {@link GSAPTweenVars} remain untouched.
-   */
-  protected prepareAnimationDefinition() {
-    // create an animation definition if not available yet
-    this._animationDefinition = this._animationDefinition || {};
-
-    // parse shortest way flag or set to `true` if not configured
-    if (this._animationDefinition.shortestWay !== undefined) {
-      this._animationDefinition.shortestWay = Parameter.parseBoolean(this._animationDefinition.shortestWay);
-    } else {
-      this._animationDefinition.shortestWay = true;
-    }
-  }
-
-  /**
-   * Prepares different types of {@link PlacementDefinition} and sets some defaults.
-   */
-  protected preparePlacementDefinition() {
-    let position = this._placementDefinition.position;
-    if (isString(position)) {
-      position = Parameter.parseVector(position);
-      this._placementDefinition.position = position;
-    }
-    if (this.mutable instanceof ArcRotateCamera) {
-      // parse the target
-      if (isString(this._placementDefinition.target)) {
-        this._placementDefinition.target = Parameter.parseVector(this._placementDefinition.target);
-      }
-      if (position) {
-        // parse the position and calculate alpha, beta and radius with a "ghost camera"
-        // @see https://www.babylonjs-playground.com/#4IVMG#0
-        const ghostCam = (this.mutable as ArcRotateCamera).clone('ghost') as ArcRotateCamera;
-        ghostCam.setPosition(position);
-        merge(this._placementDefinition, {
-          alpha: ghostCam.alpha,
-          beta: ghostCam.beta,
-          radius: ghostCam.radius,
-        });
-        delete this._placementDefinition.position;
-        ghostCam.dispose();
-      } else if (this._animationDefinition.shortestWay && this._placementDefinition.alpha !== undefined) {
-        // transform the target's alpha value into the same turn as the current camera position to avoid movements
-        // > 360 degrees
-        const alphaGap = this.mutable.alpha - this._placementDefinition.alpha;
-        const cntTurns = Math.round(alphaGap / (2 * Math.PI));
-        this._placementDefinition.alpha += 2 * Math.PI * cntTurns;
-      }
-    }
-  }
-
-  /**
-   * Creates `Tweens` for the {@link PlacementDefinition} configured for this {@link PlacementAnimation}.
-   */
-  protected createTweens() {
-    for (const property in this._placementDefinition) {
-      const propertyValue = get(this._placementDefinition, property);
-      const tweenVars: object = {};
-      let _mutable = this.mutable;
-      if (propertyValue instanceof Vector3) {
-        // GSAP does not support mutation of complex objects, so we are forced
-        // to use the properties on the object as mutable directly and mutate
-        // the coordinates separately.
-        _mutable = get(this.mutable, property);
-        merge(tweenVars, { x: propertyValue.x, y: propertyValue.y, z: propertyValue.z });
-      } else {
-        set(tweenVars, property, propertyValue);
-      }
-      this._timeline.to(_mutable, tweenVars, 0); // Note: position 0 does the "parallel" stuff here
-    }
-  }
-}
+import { Parameter } from '../classes/parameter';
+import { SpecStorage } from '../store/specStorage';
+import { AnimationInterface } from './animationInterface';
+import { ArcRotateCamera } from '@babylonjs/core/Cameras/arcRotateCamera';
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import { gsap } from 'gsap';
+import { cloneDeep, get, isString, merge, set } from 'lodash-es';
+
+/**
+ * An {@link PlacementAnimation} handling `Tweens` of the `GSAP` API using configured {@link PlacementDefinition}s
+ * and {@link AnimationDefinition}s. It mutates the attributes in the given {@link PlacementDefinition} with the given
+ * {@link AnimationDefinition}. The latter can be anything the `GSAP` allows in its API. Please consider using the
+ * API of the {@link AnimationManager} to handle instances of this class in your consuming project.
+ */
+export class PlacementAnimation implements AnimationInterface {
+  protected _placementDefinition: PlacementDefinition;
+
+  protected _animationDefinition: AnimationDefinition;
+
+  protected _timeline: GSAPTimeline;
+
+  /**
+   * Constructor.
+   */
+  public constructor(
+    public readonly mutable: object,
+    protected _placement: PlacementDefinition | string,
+    protected _animation?: AnimationDefinition | string
+  ) {
+    if (isString(_placement)) {
+      const placementDefinitions = SpecStorage.get<PlacementDefinitions>('scene.placements');
+      if (!placementDefinitions) {
+        throw new Error(`No PlacementDefinitions defined in JSON structure.`);
+      }
+      const placementDefinition = placementDefinitions[_placement];
+      if (!placementDefinition) {
+        throw new Error(`PlacementDefinition "${_placement}" not defined in JSON structure.`);
+      }
+      this._placementDefinition = cloneDeep(placementDefinition);
+    } else {
+      this._placementDefinition = cloneDeep(_placement) as PlacementDefinition;
+    }
+    if (isString(_animation)) {
+      const animationDefinition = SpecStorage.get<AnimationDefinitions>('scene.animations')?.[_animation];
+      if (!animationDefinition) {
+        throw new Error(`AnimationDefinition "${_animation}" not defined in JSON structure.`);
+      }
+      this._animationDefinition = cloneDeep(animationDefinition);
+    } else {
+      this._animationDefinition = cloneDeep(_animation) as AnimationDefinition;
+    }
+
+    this.prepareAnimationDefinition();
+    // create (shallow) copy for GSAP which doesn't contain `shortestWay`,
+    // because that's not part of the original `TweenVars` input typing and therefore leads to warnings
+    const { shortestWay, ...gsapTweenVars } = this._animationDefinition;
+    this._timeline = gsap.timeline({
+      defaults: gsapTweenVars,
+      paused: true,
+    });
+
+    this.preparePlacementDefinition();
+    this.createTweens();
+  }
+
+  /**
+   * Plays all `Tweens` of this {@link PlacementAnimation}.
+   */
+  public async play(): Promise<AnimationInterface> {
+    await this._timeline.play().then();
+    return this;
+  }
+
+  /**
+   * Pause all `Tweens` of this {@link PlacementAnimation}.
+   */
+  public pause(): AnimationInterface {
+    this._timeline.pause();
+    return this;
+  }
+
+  /**
+   * Kills all `Tweens` of this {@link PlacementAnimation}.
+   */
+  public kill(): AnimationInterface {
+    this._timeline.kill();
+    return this;
+  }
+
+  /**
+   * Creates a {@link AnimationDefinition} definition if not provided in the constructor and sets some defaults.
+   * Only custom properties from {@link AnimationDefinition} are adjusted, all {@link GSAPTweenVars} remain untouched.
+   */
+  protected prepareAnimationDefinition() {
+    // create an animation definition if not available yet
+    this._animationDefinition = this._animationDefinition || {};
+
+    // parse shortest way flag or set to `true` if not configured
+    if (this._animationDefinition.shortestWay !== undefined) {
+      this._animationDefinition.shortestWay = Parameter.parseBoolean(this._animationDefinition.shortestWay);
+    } else {
+      this._animationDefinition.shortestWay = true;
+    }
+  }
+
+  /**
+   * Prepares different types of {@link PlacementDefinition} and sets some defaults.
+   */
+  protected preparePlacementDefinition() {
+    let position = this._placementDefinition.position;
+    if (isString(position)) {
+      position = Parameter.parseVector(position);
+      this._placementDefinition.position = position;
+    }
+    if (this.mutable instanceof ArcRotateCamera) {
+      // parse the target
+      if (isString(this._placementDefinition.target)) {
+        this._placementDefinition.target = Parameter.parseVector(this._placementDefinition.target);
+      }
+      if (position) {
+        // parse the position and calculate alpha, beta and radius with a "ghost camera"
+        // @see https://www.babylonjs-playground.com/#4IVMG#0
+        const ghostCam = (this.mutable as ArcRotateCamera).clone('ghost') as ArcRotateCamera;
+        ghostCam.setPosition(position);
+        merge(this._placementDefinition, {
+          alpha: ghostCam.alpha,
+          beta: ghostCam.beta,
+          radius: ghostCam.radius,
+        });
+        delete this._placementDefinition.position;
+        ghostCam.dispose();
+      } else if (this._animationDefinition.shortestWay && this._placementDefinition.alpha !== undefined) {
+        // transform the target's alpha value into the same turn as the current camera position to avoid movements
+        // > 360 degrees
+        const alphaGap = this.mutable.alpha - this._placementDefinition.alpha;
+        const cntTurns = Math.round(alphaGap / (2 * Math.PI));
+        this._placementDefinition.alpha += 2 * Math.PI * cntTurns;
+      }
+    }
+  }
+
+  /**
+   * Creates `Tweens` for the {@link PlacementDefinition} configured for this {@link PlacementAnimation}.
+   */
+  protected createTweens() {
+    for (const property in this._placementDefinition) {
+      const propertyValue = get(this._placementDefinition, property);
+      const tweenVars: object = {};
+      let _mutable = this.mutable;
+      if (propertyValue instanceof Vector3) {
+        // GSAP does not support mutation of complex objects, so we are forced
+        // to use the properties on the object as mutable directly and mutate
+        // the coordinates separately.
+        _mutable = get(this.mutable, property);
+        merge(tweenVars, { x: propertyValue.x, y: propertyValue.y, z: propertyValue.z });
+      } else {
+        set(tweenVars, property, propertyValue);
+      }
+      this._timeline.to(_mutable, tweenVars, 0); // Note: position 0 does the "parallel" stuff here
+    }
+  }
+}