@combeenation/3d-viewer 7.0.0 → 7.1.0

package/src/api/classes/parameterObservable.ts

@@ -1,73 +1,73 @@
-import { uuidv4 } from '../util/stringHelper';
-import { EventBroadcaster } from './eventBroadcaster';
-import { Parameter } from './parameter';
-import { merge } from 'lodash-es';
-
-export abstract class ParameterObservable extends EventBroadcaster {
-  public readonly uuid: string;
-
-  public readonly parameters: ParameterBag = {};
-
-  protected readonly parameterDeclaration: ParameterDeclarations = {};
-
-  protected parameterObservers: Map<string, ParameterObserver[]> = new Map();
-
-  protected constructor(parameterDeclaration: ParameterDeclarations = {}, parameters: ParameterBag = {}) {
-    super();
-    this.uuid = uuidv4();
-    this.parameterDeclaration = merge(this.parameterDeclaration, parameterDeclaration);
-    this.parameters = merge(this.parameters, parameters);
-  }
-
-  /**
-   * The uuid (if not overloaded).
-   */
-  get id(): string {
-    return this.uuid;
-  }
-
-  /**
-   * Adds an observer function for parameter changes.
-   * The {@link ParameterObserver} gets 3 parameters: the {@link ParameterObservable}, the old {@link ParameterValue}
-   * and the new {@link ParameterValue}.
-   *
-   * See {@page ../../../doc/documentation/Parameters.md} for an example.
-   */
-  public addParameterObserver(parameter: string, observer: ParameterObserver): ParameterObservable {
-    if (this.parameterObservers.has(parameter)) {
-      this.parameterObservers.get(parameter)!.push(observer);
-      return this;
-    }
-    this.parameterObservers.set(parameter, [observer]);
-    return this;
-  }
-
-  /**
-   * Removes all {@link ParameterObserver}s for given parameter.
-   */
-  public removeParameterObservers(parameter: string): ParameterObservable {
-    this.parameterObservers.delete(parameter);
-    return this;
-  }
-
-  /**
-   * Invoke parameter observers for given parameter.
-   */
-  public async commitParameter(parameter: string, value: ParameterValue): Promise<ParameterObservable> {
-    const parameters: ParameterBag = {};
-    parameters[parameter] = value;
-    return this.commitParameters(parameters);
-  }
-
-  /**
-   * Invoke parameter observers for given parameters.
-   */
-  public abstract commitParameters(parameters?: ParameterBag): Promise<ParameterObservable>;
-
-  /**
-   * Asserts whether given parameter is declared and valid.
-   */
-  public assertParameter(parameterDeclaration: ParameterDeclarations, parameter: string, value: ParameterValue) {
-    Parameter.assertParameter(parameterDeclaration, parameter, value);
-  }
-}
+import { uuidv4 } from '../util/stringHelper';
+import { EventBroadcaster } from './eventBroadcaster';
+import { Parameter } from './parameter';
+import { merge } from 'lodash-es';
+
+export abstract class ParameterObservable extends EventBroadcaster {
+  public readonly uuid: string;
+
+  public readonly parameters: ParameterBag = {};
+
+  protected readonly parameterDeclaration: ParameterDeclarations = {};
+
+  protected parameterObservers: Map<string, ParameterObserver[]> = new Map();
+
+  protected constructor(parameterDeclaration: ParameterDeclarations = {}, parameters: ParameterBag = {}) {
+    super();
+    this.uuid = uuidv4();
+    this.parameterDeclaration = merge(this.parameterDeclaration, parameterDeclaration);
+    this.parameters = merge(this.parameters, parameters);
+  }
+
+  /**
+   * The uuid (if not overloaded).
+   */
+  get id(): string {
+    return this.uuid;
+  }
+
+  /**
+   * Adds an observer function for parameter changes.
+   * The {@link ParameterObserver} gets 3 parameters: the {@link ParameterObservable}, the old {@link ParameterValue}
+   * and the new {@link ParameterValue}.
+   *
+   * See [Parameters](https://3dviewer.docs.combeenation.com/pages/documentation/Parameters.html) for an example.
+   */
+  public addParameterObserver(parameter: string, observer: ParameterObserver): ParameterObservable {
+    if (this.parameterObservers.has(parameter)) {
+      this.parameterObservers.get(parameter)!.push(observer);
+      return this;
+    }
+    this.parameterObservers.set(parameter, [observer]);
+    return this;
+  }
+
+  /**
+   * Removes all {@link ParameterObserver}s for given parameter.
+   */
+  public removeParameterObservers(parameter: string): ParameterObservable {
+    this.parameterObservers.delete(parameter);
+    return this;
+  }
+
+  /**
+   * Invoke parameter observers for given parameter.
+   */
+  public async commitParameter(parameter: string, value: ParameterValue): Promise<ParameterObservable> {
+    const parameters: ParameterBag = {};
+    parameters[parameter] = value;
+    return this.commitParameters(parameters);
+  }
+
+  /**
+   * Invoke parameter observers for given parameters.
+   */
+  public abstract commitParameters(parameters?: ParameterBag): Promise<ParameterObservable>;
+
+  /**
+   * Asserts whether given parameter is declared and valid.
+   */
+  public assertParameter(parameterDeclaration: ParameterDeclarations, parameter: string, value: ParameterValue) {
+    Parameter.assertParameter(parameterDeclaration, parameter, value);
+  }
+}

package/src/api/classes/parameterizable.ts

@@ -1,87 +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;
-  }
-}
+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

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