@combeenation/3d-viewer 4.0.0-beta4 → 4.0.0-beta5

package/src/api/classes/placementAnimation.ts

@@ -1,133 +1,143 @@
-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';
-import { Parameter } from '../classes/parameter';
-import { SpecStorage } from '../store/specStorage';
-
-/**
- * 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._timeline = gsap.timeline( {
-			defaults: merge( { duration: 0, ease: 'none' }, this._animationDefinition ),
-			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;
-	}
-
-	/**
-	 * 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();
-			}
-		}
-	}
-
-	/**
-	 * 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 { 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';
+import { Parameter } from '../classes/parameter';
+import { SpecStorage } from '../store/specStorage';
+
+/**
+ * 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._timeline = gsap.timeline( {
+			defaults: merge( { duration: 0, ease: 'none' }, this._animationDefinition ),
+			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;
+	}
+
+	/**
+	 * 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;
+		}
+		let shortestWay = true;
+		if( this._animationDefinition.shortestWay !== undefined ) {
+			shortestWay = Parameter.parseBoolean( this._animationDefinition.shortestWay );
+			this._animationDefinition.shortestWay = shortestWay;
+		}
+		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( shortestWay && this._placementDefinition.alpha ) {
+				// 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
+		}
+	}
+
+}