@combeenation/3d-viewer 4.0.0-beta3 → 4.0.0

package/src/api/classes/parameterObservable.ts

@@ -1,6 +1,5 @@
 import { merge } from 'lodash-es';
-import { Parameter } from '../classes/parameter';
-import { uuidv4 } from '../util/resourceHelper';
+import { uuidv4 } from '../util/stringHelper';
 import { EventBroadcaster } from './eventBroadcaster';
 
 export abstract class ParameterObservable extends EventBroadcaster {
@@ -75,37 +74,16 @@ export abstract class ParameterObservable extends EventBroadcaster {
 			return;
 		}
 		const declaration = parameterDeclaration[parameter];
-		const genericError = `"${value}" is not a valid value for parameter "${parameter}" of type ` +
+		const genericError = `"${value}" is not a valid value for parameter "${parameter}" of type. ` +
 			`"${declaration.type}" for ${this.constructor.name} "${this.id}".`;
+		if( declaration.parser ) {
+			try {
+				declaration.parser( value );
+			} catch( e ) {
+				throw Error( genericError + e.message );
+			}
+		}
 		switch( declaration.type ) {
-			case 'boolean':
-				try {
-					Parameter.parseBoolean( value );
-				} catch( e ) {
-					throw Error( genericError );
-				}
-				break;
-			case 'number':
-				try {
-					Parameter.parseNumber( value );
-				} catch( e ) {
-					throw Error( genericError );
-				}
-				break;
-			case 'color':
-				try {
-					Parameter.parseColor( value );
-				} catch( e ) {
-					throw Error( genericError +	` It must be hex with leading "#" or of format "(r,g,b)".` );
-				}
-				break;
-			case 'vector':
-				try {
-					Parameter.parseVector( value );
-				} catch( e ) {
-					throw Error( genericError + ` It must be of format "(x,y,z)".` );
-				}
-				break;
 			case 'select':
 				if( !declaration.options ) {
 					throw Error( `No options defined for parameter declaration "${parameter}"` +

package/src/api/classes/{elementParameterizable.ts → parameterizable.ts}

@@ -1,7 +1,7 @@
 import { Parameter } from './parameter';
 import { ParameterObservable } from './parameterObservable';
 
-export abstract class ElementParameterizable extends ParameterObservable {
+export abstract class Parameterizable extends ParameterObservable {
 
 	protected parameterDeclaration: ParameterDeclarations = Parameter.declarations;
 
@@ -55,6 +55,17 @@ export abstract class ElementParameterizable extends ParameterObservable {
 		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;

package/src/api/classes/placementAnimation.ts

@@ -88,6 +88,11 @@ export class PlacementAnimation implements AnimationInterface {
 			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 ) ) {
@@ -105,6 +110,11 @@ export class PlacementAnimation implements AnimationInterface {
 				} );
 				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);
 			}
 		}
 	}

package/src/api/classes/variant.ts

@@ -1,4 +1,5 @@
 import { AssetContainer } from '@babylonjs/core/assetContainer';
+import { Light } from '@babylonjs/core/Lights/light';
 import '@babylonjs/core/Loading/Plugins/babylonFileLoader';
 import { SceneLoader } from '@babylonjs/core/Loading/sceneLoader';
 import { Material } from '@babylonjs/core/Materials/material';
@@ -7,19 +8,18 @@ import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
 import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression';
 import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_texture_transform';
 import '@babylonjs/loaders/glTF/2.0/glTFLoader';
-import { cloneDeep, concat, isEmpty, isEqual, isString, merge } from 'lodash-es';
-import {
-	deactivateTransformNode,
-	getDottedPathForTransformNode,
-	injectTransformNodeMetadata
-} from '../util/babylonHelper';
+import { cloneDeep, concat, get, isEmpty, isEqual, isString, merge, set } from 'lodash-es';
+import { deactivateTransformNode, getDottedPathForNode, injectNodeMetadata } from '../util/babylonHelper';
 import { loadJson, mergeMaps } from '../util/resourceHelper';
 import { DottedPath } from './dottedPath';
 import { Element } from './element';
-import { ElementParameterizable } from './elementParameterizable';
 import { Event } from './event';
 import { Parameter } from './parameter';
+import { Parameterizable } from './parameterizable';
+import { ParameterObservable } from './parameterObservable';
+import { VariantParameterizable } from './variantParameterizable';
 import { Viewer } from './viewer';
+import { ViewerLight } from './viewerLight';
 
 import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_texture_basisu';
 import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_clearcoat';
@@ -35,12 +35,14 @@ import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_variants';
 /**
  * A concrete "Variant". Most of these are handled by either the {@link Viewer} or {@link VariantInstance}.
  */
-export class Variant extends ElementParameterizable {
+export class Variant extends Parameterizable {
 
 	public assetContainer: AssetContainer;
 
 	public readonly elements: Element[] = [];
 
+	public readonly viewerLights: ViewerLight[] = [];
+
 	public structureJson: StructureJson;
 
 	protected _dottedNodes: Map<DottedPath, TransformNode> | undefined;
@@ -175,6 +177,13 @@ export class Variant extends ElementParameterizable {
 		return rootNodes;
 	}
 
+	/**
+	 * The {@link ViewerLight}s of the {@link Variant}.
+	 */
+	get lights(): Light[] {
+		return this.assetContainer.lights;
+	}
+
 	/**
 	 * All TransformNodes of the {@link Variant} mapped flat with a {@link DottedPath}.
 	 */
@@ -208,6 +217,17 @@ export class Variant extends ElementParameterizable {
 		return concat( elements, this.elements );
 	}
 
+	/**
+	 * All {@link ViewerLight}s inherited from this {@link Variant}'s parents.
+	 */
+	get inheritedViewerLights(): ViewerLight[] {
+		let viewerLights: ViewerLight[] = [];
+		this.ancestors.forEach( ancestor => {
+			viewerLights = concat( viewerLights, ancestor.viewerLights );
+		} );
+		return concat( viewerLights, this.viewerLights );
+	}
+
 	/**
 	 * All TransformNodes inherited from this {@link Variant}'s parents.
 	 */
@@ -230,6 +250,17 @@ export class Variant extends ElementParameterizable {
 		return dottedNodes;
 	}
 
+	/**
+	 * All Lights inherited from this {@link Variant}'s parents.
+	 */
+	get inheritedLights(): Light[] {
+		let lights: Light[] = [];
+		this.ancestors.forEach( ancestor => {
+			lights = concat( lights, ancestor.lights );
+		} );
+		return concat( lights, this.lights );
+	}
+
 	/**
 	 * The {@link ParameterDeclarations} inherited from this {@link Variant}'s parents.
 	 */
@@ -337,6 +368,33 @@ export class Variant extends ElementParameterizable {
 		return element;
 	}
 
+	/**
+	 * Gets the desired {@link ViewerLight} of the current {@link Variant} relative to its {@link DottedPath}.
+	 * Uses the mechanism of {@link getDescendant} to resolve the appropriate variant in tree.
+	 */
+	public async getViewerLight( dottedPath: DottedPathArgument ): Promise<ViewerLight> {
+		const _dottedPath = DottedPath.create( dottedPath );
+		const viewerLightName = _dottedPath.popPart();
+		let variant: Variant = this;
+		if( _dottedPath.parts.length > 0 ) {
+			variant = await this.getDescendant( _dottedPath );
+		}
+		if( variant.inheritedViewerLights.length === 0 ) {
+			throw new Error( `No viewerLights for variant "${variant.id}" found. ` +
+				`Either none are defined or they are not initialized (are you operating on the appropriate living?).` );
+		}
+		let viewerLight;
+		variant.inheritedViewerLights.forEach( _viewerLight => {
+			if( _viewerLight.name === viewerLightName ) {
+				viewerLight = _viewerLight;
+			}
+		} );
+		if( !viewerLight ) {
+			throw new Error( `ViewerLight with name "${viewerLightName}" does not exist for variant "${variant.id}".` );
+		}
+		return viewerLight;
+	}
+
 	/**
 	 * A proxy for directly getting a Node from an {@link Element} by its {@link DottedPath}s.
 	 */
@@ -383,7 +441,8 @@ export class Variant extends ElementParameterizable {
 		parent?._children.set( variant.name, variant );
 		variant.assetContainer = this.assetContainer;
 		variant.parameterObservers = cloneDeep( this.parameterObservers );
-		variant.createElements();
+		await variant.createElements();
+		await variant.createViewerLights();
 		variant.addParameterObservers();
 		await variant.bootstrapParameters( parameters );
 		this.broadcastEvent( Event.VARIANT_CREATED, variant );
@@ -489,31 +548,10 @@ export class Variant extends ElementParameterizable {
 		this.broadcastEvent(Event.VARIANT_PARAMETER_BAG_COMMITTED, this, oldParameters, newParameters);
 
 		// commit parameters to elements
-		const elementPromises: Promise<Element>[] = this.elements.map( element => {
-			let _elementDefinition = JSON.stringify( this._structureJson.elements![element.name] );
-			const elementParameters: ParameterBag = {};
-			for( const parameter in newParameters ) {
-				if( DottedPath.create( parameter ).firstPart !== element.name ) {
-					continue;
-				}
-				// we got an element parameter
-				let newParameterValue = newParameters[parameter];
-				const elementParameter = parameter.replace( `${element.name}.`, '' );
-				// If the variant is explicitly hidden, we must not override the visibility with element parameters. We need
-				// an exception for visibility to avoid overloading already applied element parameters with element parameters
-				// defined in the variant spec ("dotted parameters").
-				// @see https://github.com/Combeenation/3d-viewer/issues/44
-				if( elementParameter === Parameter.VISIBLE && newParameters[Parameter.VISIBLE] === false ) {
-					newParameterValue = false;
-				}
-				elementParameters[elementParameter] = newParameterValue;
-				const search = new RegExp( `\\$\\{${elementParameter}\\}`, 'g' );
-				_elementDefinition = _elementDefinition.replace( search, newParameterValue.toString() );
-			}
-			this.structureJson.elements![this.name] = JSON.parse( _elementDefinition );
-			return element.commitParameters( elementParameters );
-		} );
-		await Promise.all( elementPromises );
+		await this.commitParametersToElements( newParameters );
+
+		// commit parameters to lights
+		await this.commitParametersToViewerLights( newParameters );
 
 		// propagate parameters to parent
 		if( this.parent ) {
@@ -562,7 +600,17 @@ export class Variant extends ElementParameterizable {
 				const nodes = this.assetContainer.getNodes().filter( n => n instanceof TransformNode ) as TransformNode[];
 				nodes.forEach( node => {
 					deactivateTransformNode( node, false );
-					injectTransformNodeMetadata( node, { dottedPath: getDottedPathForTransformNode( node ) }, false );
+					injectNodeMetadata( node, { dottedPath: getDottedPathForNode( node ) }, false );
+				} );
+				this.assetContainer.lights.forEach( light => {
+					light.setEnabled( false );
+					injectNodeMetadata( light, { dottedPath: getDottedPathForNode( light ) }, false );
+					this.viewer.scene.addLight( light );
+				} );
+				this.assetContainer.cameras.forEach( camera => {
+					camera.setEnabled( false );
+					injectNodeMetadata( camera, { dottedPath: getDottedPathForNode( camera ) }, false );
+					this.viewer.scene.addCamera( camera );
 				} );
 				this.broadcastEvent( Event.ASSET_LOADING_END, this );
 				resolve( this );
@@ -573,15 +621,82 @@ export class Variant extends ElementParameterizable {
 		} );
 	}
 
+	/**
+	 * Commits given parameters to all {@link Element}s.
+	 */
+	protected async commitParametersToElements( parameters: ParameterBag ) {
+		await Promise.all( this.elements.map(
+			element => this.commitParametersToVariantParameterizable(parameters, element, 'elements')
+		) );
+	}
+
+	/**
+	 * Commits given parameters to all {@link ViewerLight}s.
+	 */
+	protected async commitParametersToViewerLights( parameters: ParameterBag ) {
+		await Promise.all( this.viewerLights.map(
+			viewerLight => this.commitParametersToVariantParameterizable(parameters, viewerLight, 'lights')
+		) );
+	}
+
+	/**
+	 * Commits given parameters to a {@link VariantParameterizable} and updates the according definition with given
+	 * key in the {@link StructureJson}. The `definitionKey` "elements" for example will update the definition in
+	 * `this.structureJson.elements`.
+	 */
+	protected async commitParametersToVariantParameterizable( parameters: ParameterBag,
+	                                                          parameterizable: VariantParameterizable,
+	                                                          definitionKey: string ): Promise<ParameterObservable> {
+		const initialDefinition = get( this._structureJson, definitionKey )[parameterizable.name];
+		let initialDefinitionStr = JSON.stringify( initialDefinition );
+		const _parameters: ParameterBag = {};
+		for( const parameter in parameters ) {
+			const dpp = DottedPath.create( parameter );
+			if( dpp.shiftPart() !== parameterizable.name ) {
+				continue;
+			}
+			// we got a parameterizable ("element") parameter
+			let parameterValue = parameters[parameter];
+			const parameterizableParameter = dpp.path;
+			// If the variant is explicitly hidden, we must not override the visibility with element parameters. We need
+			// an exception for visibility to avoid overloading already applied element parameters with element parameters
+			// defined in the variant spec ("dotted parameters").
+			// @see https://github.com/Combeenation/3d-viewer/issues/44
+			if( parameterizableParameter === Parameter.VISIBLE && parameters[Parameter.VISIBLE] === false ) {
+				parameterValue = false;
+			}
+			_parameters[parameterizableParameter] = parameterValue;
+			const search = new RegExp( `\\$\\{${parameterizableParameter}\\}`, 'g' );
+			initialDefinitionStr = initialDefinitionStr.replace( search, parameterValue.toString() );
+		}
+		const definition = get( this.structureJson, definitionKey );
+		definition[this.name] = JSON.parse( initialDefinitionStr );
+		set( this.structureJson, definitionKey, definition );
+		return await parameterizable.commitParameters( _parameters );
+	}
+
 	/**
 	 * Commits given {@link Parameter} to the {@link Variant}'s {@link Element}s.
 	 */
-	protected async commitParameterToElements( parameter: string, value: ParameterValue ) {
+	protected async commitParameterToElements( parameter: string, value: ParameterValue ): Promise<Variant> {
 		const promises = [];
 		for( const element of this.elements ) {
 			promises.push( element.commitParameter( parameter, value ) );
 		}
 		await Promise.all( promises );
+		return this;
+	}
+
+	/**
+	 * Commits given {@link Parameter} to the {@link Variant}'s {@link Element}s.
+	 */
+	protected async commitParameterToViewerLights( parameter: string, value: ParameterValue ): Promise<Variant> {
+		const promises = [];
+		for( const viewerLight of this.viewerLights ) {
+			promises.push( viewerLight.commitParameter( parameter, value ) );
+		}
+		await Promise.all( promises );
+		return this;
 	}
 
 	/**
@@ -591,11 +706,13 @@ export class Variant extends ElementParameterizable {
 		this._parameterObservers.set( Parameter.VISIBLE, [
 			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
 				await variant.commitParameterToElements( Parameter.VISIBLE, newValue );
+				await variant.commitParameterToViewerLights( Parameter.VISIBLE, newValue );
 			}
 		] );
 		this._parameterObservers.set( Parameter.SCALING, [
 			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
 				await variant.commitParameterToElements( Parameter.SCALING, newValue );
+				await variant.commitParameterToViewerLights( Parameter.SCALING, newValue );
 			}
 		] );
 		this._parameterObservers.set( Parameter.MATERIAL, [
@@ -631,11 +748,28 @@ export class Variant extends ElementParameterizable {
 		this._parameterObservers.set( Parameter.POSITION, [
 			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
 				await variant.commitParameterToElements( Parameter.POSITION, newValue );
+				await variant.commitParameterToViewerLights( Parameter.POSITION, newValue );
 			}
 		] );
 		this._parameterObservers.set( Parameter.ROTATION, [
 			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
 				await variant.commitParameterToElements( Parameter.ROTATION, newValue );
+				await variant.commitParameterToViewerLights( Parameter.ROTATION, newValue );
+			}
+		] );
+		this._parameterObservers.set( Parameter.CAST_SHADOW, [
+			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				await variant.commitParameterToElements( Parameter.CAST_SHADOW, newValue );
+			}
+		] );
+		this._parameterObservers.set( Parameter.CAST_SHADOW_FROM_LIGHTS, [
+			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				await variant.commitParameterToElements( Parameter.CAST_SHADOW_FROM_LIGHTS, newValue );
+			}
+		] );
+		this._parameterObservers.set( Parameter.RECEIVE_SHADOWS, [
+			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				await variant.commitParameterToElements( Parameter.RECEIVE_SHADOWS, newValue );
 			}
 		] );
 		return this;
@@ -644,20 +778,33 @@ export class Variant extends ElementParameterizable {
 	/**
 	 * Creates {@link Element}s and clones nodes into them.
 	 */
-	protected createElements(): Variant {
-		for( const elementName in this.structureJson.elements || {} ) {
-			this.elements.push( new Element( this, elementName ) );
+	protected async createElements(): Promise<Variant> {
+		for( const name in this.structureJson.elements || {} ) {
+			this.elements.push( await Element.create( this, name ) );
 		}
 		// inject node meta to all inherited elements
 		// we do this to inject the deepest and most concrete variant information to all cloned nodes in the tree
 		this.inheritedElements.forEach( element => {
 			element.nodes.forEach( node => {
-				injectTransformNodeMetadata( node, { variant: this, element: element } );
+				injectNodeMetadata( node, { variant: this, variantParameterizable: element } );
 			} );
 		} );
 		return this;
 	}
 
+	/**
+	 * Creates {@link ViewerLight}s.
+	 */
+	protected async createViewerLights(): Promise<Variant> {
+		for( const name in this.structureJson.lights || {} ) {
+			this.viewerLights.push( await ViewerLight.create( this, name ) );
+		}
+		this.inheritedViewerLights.forEach( viewerLight => {
+			injectNodeMetadata( viewerLight.light, { variant: this, variantParameterizable: viewerLight } );
+		} );
+		return this;
+	}
+
 	/**
 	 * Bootstrapping for parameters. It sets the `parametersInitialized` to true for all ancestors.
 	 */

package/src/api/classes/variantInstance.ts

@@ -1,6 +1,6 @@
 import { Mesh } from '@babylonjs/core/Meshes/mesh';
-import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
 import { Element } from './element';
+import { ViewerLight } from './viewerLight';
 import { EventBroadcaster } from './eventBroadcaster';
 import { ParameterObservable } from './parameterObservable';
 import { Variant } from './variant';
@@ -51,6 +51,13 @@ export class VariantInstance extends EventBroadcaster {
 		return this.variant.getElement( dottedPath );
 	}
 
+	/**
+	 * A proxy for {@link Variant.getViewerLight}.
+	 */
+	public async getViewerLight( dottedPath: DottedPathArgument ): Promise<ViewerLight> {
+		return this.variant.getViewerLight( dottedPath );
+	}
+
 	/**
 	 * A proxy for {@link Variant.getNode}.
 	 */

package/src/api/classes/variantParameterizable.ts

@@ -0,0 +1,73 @@
+import { DottedPath } from './../classes/dottedPath';
+import { Event } from './../classes/event';
+import { Parameterizable } from './../classes/parameterizable';
+import { Variant } from './../classes/variant';
+import { mergeMaps } from './../util/resourceHelper';
+import { camelToSnakeCase } from './../util/stringHelper';
+import { cloneDeep, concat, get, merge } from 'lodash-es';
+
+export abstract class VariantParameterizable extends Parameterizable {
+
+	protected readonly _parameterObservers: Map<string, ParameterObserver[]> = new Map();
+
+	protected constructor( public readonly variant: Variant,
+	                       public readonly name: string ) {
+		super();
+	}
+
+	/**
+	 * Gets the inherited parameters from the {@link Variant} with cleaned {@link Parameterizable} prefix.
+	 */
+	get inheritedParameters(): ParameterBag {
+		const parameterBag: ParameterBag = {};
+		for( const parameter in this.variant.inheritedParameters ) {
+			const dpp = DottedPath.create( parameter );
+			if( dpp.firstPart !== this.name ) {
+				continue;
+			}
+			dpp.shiftPart();
+			parameterBag[dpp.path] = this.variant.inheritedParameters[parameter];
+		}
+		return parameterBag;
+	}
+
+	/**
+	 * Places the given {@link ParameterBag} in the {@link VariantParameterizable}'s parameters, replaces all patterns in the
+	 * {@link StructureJson} and broadcasts all {@link ParameterObserver}s.
+	 */
+	public async commitParameters( parameters?: ParameterBag ): Promise<VariantParameterizable> {
+		if( !parameters ) {
+			parameters = {};
+		}
+		const oldParameters = cloneDeep( this.parameters );
+		merge( this.parameters, parameters );
+		// handle parameter observers
+		let observerPromises: Promise<void | ParameterObserver>[] = [];
+		for( const parameter in this.parameters ) {
+			const oldParameterValue = oldParameters[parameter];
+			const newParameterValue = this.parameters[parameter];
+			this.variant.assertParameter( this.variant.inheritedParameterDeclaration, parameter, newParameterValue );
+			if( oldParameterValue === newParameterValue ) {
+				continue;
+			}
+			// parameter changed
+			const parameterObservers = mergeMaps( this._parameterObservers, this.parameterObservers );
+			if( parameterObservers.has( parameter ) ) {
+				const observers = parameterObservers.get( parameter )!;
+				observerPromises = concat( observerPromises, observers.map( observer => {
+					const observerResult = observer( this, oldParameterValue, newParameterValue );
+					const observerPromise = Promise.resolve( observerResult );
+					observerPromise.then( () => {
+						const clsName = camelToSnakeCase( this.constructor.name ).toUpperCase();
+						this.broadcastEvent( get( Event, clsName + '_PARAMETER_COMMITTED' ),
+							this, parameter, oldParameterValue, newParameterValue );
+					} );
+					return observerPromise;
+				} ) );
+			}
+		}
+		await Promise.all( observerPromises );
+		return this;
+	}
+
+}