@combeenation/3d-viewer 0.0.1

package/src/api/classes/parameterizable.ts

@@ -0,0 +1,87 @@
+import { Parameter } from './parameter';
+import { ParameterObservable } from './parameterObservable';
+
+export abstract class Parameterizable extends ParameterObservable {
+  protected parameterDeclaration: ParameterDeclarations = Parameter.declarations;
+
+  get visible(): boolean | undefined {
+    if (!(Parameter.VISIBLE in this.parameters)) {
+      return undefined;
+    }
+    try {
+      return Parameter.parseBoolean(this.parameters[Parameter.VISIBLE]);
+    } catch (e) {
+      return undefined;
+    }
+  }
+
+  get highlighted(): boolean | undefined {
+    if (!(Parameter.HIGHLIGHTED in this.parameters)) {
+      return undefined;
+    }
+    try {
+      return Parameter.parseBoolean(this.parameters[Parameter.HIGHLIGHTED]);
+    } catch (e) {
+      return undefined;
+    }
+  }
+
+  get material(): string | undefined {
+    if (!(Parameter.MATERIAL in this.parameters)) {
+      return undefined;
+    }
+    return this.parameters[Parameter.MATERIAL].toString();
+  }
+
+  get scaling(): string | undefined {
+    if (!(Parameter.SCALING in this.parameters)) {
+      return undefined;
+    }
+    return this.parameters[Parameter.SCALING].toString();
+  }
+
+  get position(): string | undefined {
+    if (!(Parameter.POSITION in this.parameters)) {
+      return undefined;
+    }
+    return this.parameters[Parameter.POSITION].toString();
+  }
+
+  get rotation(): string | undefined {
+    if (!(Parameter.ROTATION in this.parameters)) {
+      return undefined;
+    }
+    return this.parameters[Parameter.ROTATION].toString();
+  }
+
+  get castShadow(): boolean | undefined {
+    if (!(Parameter.CAST_SHADOW in this.parameters)) {
+      return undefined;
+    }
+    try {
+      return Parameter.parseBoolean(this.parameters[Parameter.CAST_SHADOW]);
+    } catch (e) {
+      return undefined;
+    }
+  }
+
+  public async show(): Promise<ParameterObservable> {
+    await this.commitParameter(Parameter.VISIBLE, true);
+    return this;
+  }
+
+  public async hide(): Promise<ParameterObservable> {
+    await this.commitParameter(Parameter.VISIBLE, false);
+    return this;
+  }
+
+  public async toggle(): Promise<ParameterObservable> {
+    await this.commitParameter(Parameter.VISIBLE, !this.visible);
+    return this;
+  }
+
+  public async toggleHighlight(): Promise<ParameterObservable> {
+    await this.commitParameter(Parameter.HIGHLIGHTED, !this.highlighted);
+    return this;
+  }
+}

package/src/api/classes/placementAnimation.ts

@@ -0,0 +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
+    }
+  }
+}