@combeenation/3d-viewer 4.0.0-beta4 → 4.0.1-alpha1

package/src/api/classes/viewer.ts

@@ -1,422 +1,488 @@
-import { ArcRotateCamera } from '@babylonjs/core/Cameras/arcRotateCamera';
-import { PickingInfo } from '@babylonjs/core/Collisions/pickingInfo';
-import { BoundingInfo } from '@babylonjs/core/Culling/boundingInfo';
-import { Engine } from '@babylonjs/core/Engines/engine';
-import { HighlightLayer } from '@babylonjs/core/Layers/highlightLayer';
-import { Vector3 } from '@babylonjs/core/Maths/math.vector';
-import { Mesh } from '@babylonjs/core/Meshes/mesh';
-import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
-import { ScreenshotTools } from '@babylonjs/core/Misc/screenshotTools';
-import { Scene } from '@babylonjs/core/scene';
-import { isString } from 'lodash-es';
-import { version } from '../../buildinfo.json';
-import { sceneSetup } from '../internal/sceneSetup';
-import { AnimationManager } from '../manager/animationManager';
-import { SceneManager } from '../manager/sceneManager';
-import { VariantInstanceManager } from '../manager/variantInstanceManager';
-import { SpecStorage } from '../store/specStorage';
-import { debounce, loadJson } from '../util/resourceHelper';
-import { Event } from './event';
-import { EventBroadcaster } from './eventBroadcaster';
-import { Parameter } from './parameter';
-import { Variant } from './variant';
-import { VariantInstance } from './variantInstance';
-
-
-/**
- * The main exposed object. This is the entry point into the application
- *
- * ```js
- * const canvas = document.getElementById( 'babylon-canvas' );
- * const viewer = Viewer( canvas, '/path/to/index.json' );
- * ```
- * The class does nothing on its own and needs to {@link bootstrap}
- */
-export class Viewer extends EventBroadcaster {
-
-	protected _scene: Scene | null = null;
-
-	protected _animationManager: AnimationManager | null = null;
-
-	protected _sceneManager: SceneManager | null = null;
-
-	protected _variantInstances: VariantInstanceManager | null = null;
-
-	static version = version;
-
-	/**
-	 * Constructor
-	 */
-	public constructor( public readonly canvas: HTMLCanvasElement, protected structureJson: string | StructureJson ) {
-		super();
-	}
-
-	/**
-	 * Gets the BabylonJS Scene that is attached to the instance.
-	 *
-	 * @throws Error if the `scene` has not been initialized.
-	 */
-	get scene(): Scene {
-		if( !this._scene ) {
-			throw new Error( `Scene has not been initialized.` );
-		}
-		return this._scene;
-	}
-
-	get sceneManager(): SceneManager {
-		if( !this._sceneManager ) {
-			throw new Error( `Environment has not been initialized.` );
-		}
-		return this._sceneManager;
-	}
-
-	/**
-	 * Gets the BabylonJS Engine that is attached to the viewer.
-	 */
-	get engine(): Engine {
-		return this.scene.getEngine();
-	}
-
-	/**
-	 * Gets the {@link VariantInstanceManager} attached to the viewer.
-	 *
-	 * @throws Error if the {@link VariantInstanceManager} has not been initialized.
-	 */
-	get variantInstances(): VariantInstanceManager {
-		if( !this._variantInstances ) {
-			throw Error( `There is no variantInstanceManager.` );
-		}
-		return this._variantInstances;
-	}
-
-	/**
-	 * Gets the {@link AnimationManager} attached to the viewer.
-	 *
-	 * @throws Error if the {@link AnimationManager} has not been initialized.
-	 */
-	get animationManager(): AnimationManager {
-		if( !this._animationManager ) {
-			throw new Error( `There is no animationManager instance.` );
-		}
-		return this._animationManager;
-	}
-
-	/**
-	 * Starts the application. This will
-	 * * load the given "index" JSON file
-	 * * setup the scene with the "scene" JSON file
-	 * * create an (optional) default setup with different variant settings
-	 * * sets up resizing by attaching a debounced version of {@link resize}
-	 *
-	 * @throws Error if any of the files is not found/valid
-	 *
-	 * @emits {@link Event.BOOTSTRAP_START}
-	 * @emits {@link Event.BOOTSTRAP_END}
-	 */
-	public async bootstrap(): Promise<Viewer> {
-		this.broadcastEvent( Event.BOOTSTRAP_START, this );
-		let indexJson;
-		if( isString( this.structureJson ) ) {
-			indexJson = await loadJson<StructureJson>( this.structureJson );
-		} else {
-			indexJson = this.structureJson;
-		}
-		if( !indexJson.scene ) {
-			throw new Error( `No "scene" property found for bootstrapping.` );
-		}
-		// fill spec store
-		SpecStorage.createFromSpec( indexJson );
-		// load scene
-		if( isString( indexJson.scene ) ) {
-			const sceneJson = await loadJson<SceneJson>( indexJson.scene );
-			indexJson.scene = sceneJson;
-		}
-		this._scene = await this.initScene();
-		// create instance manager
-		const rootVariant = await Variant.create( '_', indexJson, this );
-		this._variantInstances = await VariantInstanceManager.create( rootVariant );
-		// create optional default instances
-		if( indexJson.setup ) {
-			if( isString( indexJson.setup ) ) {
-				const setupJson = await loadJson<SetupJson>( indexJson.setup );
-				indexJson.setup = setupJson;
-			}
-			await this.createVariantInstances();
-		}
-		// resize handler
-		window.addEventListener( 'resize', debounce( this.resize.bind( this ), 100 ) );
-		// event broadcasting
-		this.broadcastEvent( Event.BOOTSTRAP_END, this );
-		return this;
-	}
-
-	// Disabled for now to decrease bundle size.
-	// See https://github.com/Combeenation/3d-viewer/issues/37
-	// /**
-	//  * Enables the BabylonJS DebugLayer. If you pass options, be sure to pass an Object of type `IInspectorOptions`.
-	//  */
-	// public async enableDebugLayer(options?: any) {
-	//  	// @ts-ignore
-	//  	await import(/* webpackChunkName: "debug-inspector" */'@babylonjs/inspector');
-	//  	await this.scene.debugLayer.show(options);
-	//  	return this;
-	// }
-
-	/**
-	 * Destroys all registered {@link VariantInstance}s that are registered
-	 */
-	public destroyVariantInstances(): Viewer {
-		this.variantInstances.all.forEach( variantInstance => {
-			this.variantInstances.destroy( variantInstance.name );
-		} );
-		return this;
-	}
-
-	/**
-	 * Trigger a resize event for the `Engine`
-	 */
-	public resize(): Viewer {
-		this.engine.resize();
-		return this;
-	}
-
-	/**
-	 * A convenience method for directly getting a Node from a {@link VariantInstance} and an {@link Element} by its
-	 * {@link DottedPath}s.
-	 */
-	public async getNode( variantInstanceName: string,
-	                      elementDottedPath: DottedPathArgument,
-	                      nodeDottedPath: DottedPathArgument ): Promise<TransformNode> {
-		const variantInstance = await this.variantInstances.get(variantInstanceName);
-		return variantInstance.getNode( elementDottedPath, nodeDottedPath );
-	}
-
-	/**
-	 * A convenience method for directly getting a Node from a {@link VariantInstance} and an {@link Element} by its
-	 * {@link DottedPath}s.
-	 */
-	public async getMesh( variantInstanceName: string,
-	                      elementDottedPath: DottedPathArgument,
-	                      meshDottedPath: DottedPathArgument ): Promise<Mesh|null> {
-		const variantInstance = await this.variantInstances.get(variantInstanceName);
-		return variantInstance.getMesh( elementDottedPath, meshDottedPath );
-	}
-
-	/**
-	 * Switches the camera
-	 *
-	 * @emits {@link Event.CAMERA_SWITCHED}
-	 */
-	public switchCamera( newCamera: string, reset: boolean = true ): Viewer {
-		const camera = this.scene.getCameraByName( newCamera );
-		if( camera ) {
-			const activeCamera = this.scene.activeCamera;
-			if( activeCamera ) {
-				activeCamera.detachControl( this.engine.getRenderingCanvas()! );
-			}
-			if( reset ) {
-				camera.restoreState();
-			}
-			this.scene.setActiveCameraByName( newCamera );
-			camera.attachControl( this.engine.getRenderingCanvas()! );
-			this.broadcastEvent( Event.CAMERA_SWITCHED, camera );
-		} else {
-			throw new Error( `Given camera "${newCamera}" not found.` );
-		}
-		// TODO: put traceable observers to new camera (@see element)
-		return this;
-	}
-
-	/**
-	 * Moves or animates the active camera to given `placement`.
-	 */
-	public async moveActiveCameraTo( placement: string | PlacementDefinition,
-	                                 animation?: string | AnimationDefinition ): Promise<AnimationInterface> {
-		return this.animationManager.animateToPlacement( this.sceneManager.activeCamera, placement, animation );
-	}
-
-	/**
-	 * Takes a sceenshot the the current scene. The result is a string containing a base64 encoded image
-	 */
-	public screenshot( settings?: ScreenshotSettings ): Promise<string> {
-		return new Promise( ( resolve, reject ) => {
-			if( !this.engine ) {
-				return reject( 'Engine is null' );
-			}
-			if( !this.scene ) {
-				return reject( 'Scene is null' );
-			}
-			this.scene.render();  // in combination with a render target, we need to refresh the scene manually to get the latest view
-			ScreenshotTools.CreateScreenshotUsingRenderTarget(
-				this.engine,
-				this.sceneManager.activeCamera,
-				settings?.size ?? { width: this.canvas.clientWidth, height: this.canvas.clientHeight },
-				resolve,
-				settings?.mimeType ?? 'image/png',
-				settings?.samples ?? 1,
-				settings?.antialiasing ?? false,
-				settings?.fileName ?? 'screenshot.png',
-				settings?.renderSprites ?? false
-			);
-		} );
-	}
-
-	/**
-	 * Calculates the bounding box from all visible meshes on the scene.
-	 */
-	public calculateBoundingBox(): Mesh {
-		if( this.scene.meshes.length === 0 ) {
-			throw new Error( 'There are currently no meshes on the scene.' );
-		}
-		let max = new Vector3( 0, 0, 0 );
-		let min = new Vector3( 0, 0, 0 );
-		this.scene.meshes.filter( mesh => mesh.isVisible ).forEach( mesh => {
-			max = Vector3.Maximize( max, mesh.getBoundingInfo().boundingBox.maximumWorld );
-			min = Vector3.Minimize( min, mesh.getBoundingInfo().boundingBox.minimumWorld );
-		} );
-		let boundingBox = this.scene.getMeshByName( '__bounding_box__' ) as Mesh;
-		if( !boundingBox ) {
-			boundingBox = new Mesh( '__bounding_box__', this.scene );
-		}
-		boundingBox.setBoundingInfo( new BoundingInfo( min, max ) );
-		//boundingBox.showBoundingBox = true;
-		return boundingBox;
-	}
-
-	/**
-	 * Focuses the camera to see every visible mesh in scene and tries to optimize wheel precision and panning.
-	 */
-	public autofocusActiveCamera( settings?: AutofocusSettings ) {
-		const activeCamera = this.scene.activeCamera;
-		if( !activeCamera ) {
-			throw new Error( 'No active camera found when using autofocus feature.' );
-		}
-		if( activeCamera instanceof ArcRotateCamera ) {
-			// calculate some values
-			const boundingBox = this.calculateBoundingBox();
-			const size = boundingBox.getBoundingInfo().maximum.subtract( boundingBox.getBoundingInfo().minimum );
-			let radius = size.length() * (settings?.radiusFactor ?? 1.5);
-			if( !isFinite( radius ) ) {
-				radius = 1;
-			}
-			// use helper camera to get some default values
-			const helperCamera = new ArcRotateCamera(
-				'__helper_camera__',
-				Math.PI / -2,
-				Math.PI / 2,
-				radius,
-				Vector3.Zero(),
-				this.scene
-			);
-			helperCamera.useFramingBehavior = true;
-			helperCamera.setTarget( boundingBox );
-			// translate values from helper to active camera
-			activeCamera.setTarget( Mesh.Center( [boundingBox] ) );
-			activeCamera.alpha = helperCamera.alpha;
-			activeCamera.beta = helperCamera.beta;
-			activeCamera.minZ = helperCamera.minZ;
-			activeCamera.maxZ = helperCamera.maxZ;
-			activeCamera.radius = helperCamera.radius;
-			activeCamera.lowerRadiusLimit = helperCamera.lowerRadiusLimit;
-			activeCamera.upperRadiusLimit = helperCamera.upperRadiusLimit;
-			if( settings?.adjustWheelPrecision !== false ) {
-				activeCamera.wheelPrecision = helperCamera.wheelPrecision;
-			}
-			if( settings?.adjustPanningSensibility !== false ) {
-				activeCamera.panningSensibility = helperCamera.panningSensibility;
-			}
-			if( settings?.adjustPinchPrecision !== false ) {
-				activeCamera.pinchPrecision = helperCamera.pinchPrecision;
-			}
-			// remove the helper camera
-			helperCamera.dispose();
-		} else {
-			const cameraClsName = activeCamera.getClassName();
-			throw new Error( `Camera of type "${cameraClsName}" is not implemented yet to use autofocus feature.` );
-		}
-	}
-
-	/**
-	 * Resets everything by calling {@link destroy} to clear all references and {@link bootstrap} to setup a clean
-	 * environment
-	 */
-	public async reset(): Promise<Viewer> {
-		await this.destroy();
-		return this.bootstrap();
-	}
-
-	/**
-	 * Destroys
-	 *
-	 * * all {@link VariantInstance}s using {@link destroyVariantInstances}
-	 * * calling `dispose` on the `Engine` and `Scene`
-	 */
-	public destroy(): Viewer {
-		this.destroyVariantInstances();
-		this.scene.dispose();
-		SpecStorage.destroy();
-		return this;
-	}
-
-	/**
-	 * @emits {@link Event.SCENE_PROCESSING_START}
-	 * @emits {@link Event.SCENE_PROCESSING_END}
-	 */
-	protected async initScene(): Promise<Scene> {
-		const sceneJson = SpecStorage.get<SceneJson>( 'scene' );
-		this.broadcastEvent( Event.SCENE_PROCESSING_START, sceneJson );
-		const engine = new Engine(
-			this.canvas as HTMLCanvasElement,
-			sceneJson.engine?.antialiasing ?? false,
-			sceneJson.engine?.options
-		);
-		const scene = await sceneSetup( engine, sceneJson );
-		if( sceneJson.meshPicking ) {
-			new HighlightLayer( 'default', scene );
-			scene.onPointerPick = ( pointerEvent: PointerEvent, pickInfo: PickingInfo ) => {
-				if( !pickInfo.hit ) {
-					return;
-				}
-				const mesh = pickInfo.pickedMesh;
-				this.broadcastEvent( Event.MESH_PICKED, mesh, mesh?.metadata.element, mesh?.metadata.variant );
-				if( mesh?.metadata.element ) {
-					this.broadcastEvent( Event.ELEMENT_PICKED, mesh.metadata.element );
-				}
-				if( mesh?.metadata.variant ) {
-					if( mesh.metadata.variant.inheritedParameters[Parameter.HIGHLIGHT_ENABLED] ) {
-						mesh.metadata.variant.toggleHighlight();
-					}
-					this.broadcastEvent( Event.VARIANT_PICKED, mesh.metadata.variant );
-				}
-			};
-		}
-		this._sceneManager = await SceneManager.create( scene );
-		this._animationManager = await AnimationManager.create( scene );
-		this.broadcastEvent( Event.SCENE_PROCESSING_END, scene );
-		engine.runRenderLoop( () => {
-			scene.render();
-		} );
-		return scene;
-	}
-
-	/**
-	 * Batch creation of multiple {@link VariantInstance} objects with a {@link SetupJson} object passed
-	 */
-	protected async createVariantInstances(): Promise<VariantInstance[]> {
-		const setupJson = SpecStorage.get<SetupJson>( 'setup' );
-		const instances = [];
-		for( const instanceDefinition of setupJson.instances ) {
-			if( instanceDefinition.lazy ) {
-				this.variantInstances.register( instanceDefinition );
-				continue;
-			}
-			instances.push( await this.variantInstances.create(
-				instanceDefinition.variant,
-				instanceDefinition.name,
-				instanceDefinition.parameters
-			) );
-		}
-		return instances;
-	}
-
+import { ArcRotateCamera } from '@babylonjs/core/Cameras/arcRotateCamera';
+import { PickingInfo } from '@babylonjs/core/Collisions/pickingInfo';
+import { BoundingInfo } from '@babylonjs/core/Culling/boundingInfo';
+import { Engine } from '@babylonjs/core/Engines/engine';
+import { HighlightLayer } from '@babylonjs/core/Layers/highlightLayer';
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
+import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
+import { Color3 } from '@babylonjs/core/Maths/math.color';
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import { Mesh } from '@babylonjs/core/Meshes/mesh';
+import { ScreenshotTools } from '@babylonjs/core/Misc/screenshotTools';
+import { Scene } from '@babylonjs/core/scene';
+import { isString } from 'lodash-es';
+import { version } from '../../buildinfo.json';
+import { sceneSetup } from '../internal/sceneSetup';
+import { AnimationManager } from '../manager/animationManager';
+import { SceneManager } from '../manager/sceneManager';
+import { VariantInstanceManager } from '../manager/variantInstanceManager';
+import { SpecStorage } from '../store/specStorage';
+import { debounce, loadJson, sleep } from '../util/resourceHelper';
+import { Event } from './event';
+import { EventBroadcaster } from './eventBroadcaster';
+import { Parameter } from './parameter';
+import { Variant } from './variant';
+import { VariantInstance } from './variantInstance';
+
+
+/**
+ * The main exposed object. This is the entry point into the application
+ *
+ * ```js
+ * const canvas = document.getElementById( 'babylon-canvas' );
+ * const viewer = Viewer( canvas, '/path/to/index.json' );
+ * ```
+ * The class does nothing on its own and needs to {@link bootstrap}
+ */
+export class Viewer extends EventBroadcaster {
+
+	protected _scene: Scene | null = null;
+
+	protected _animationManager: AnimationManager | null = null;
+
+	protected _sceneManager: SceneManager | null = null;
+
+	protected _variantInstances: VariantInstanceManager | null = null;
+
+	static version = version;
+
+	/**
+	 * Constructor
+	 */
+	public constructor( public readonly canvas: HTMLCanvasElement, protected structureJson: string | StructureJson ) {
+		super();
+	}
+
+	/**
+	 * Gets the BabylonJS Scene that is attached to the instance.
+	 *
+	 * @throws Error if the `scene` has not been initialized.
+	 */
+	get scene(): Scene {
+		if( !this._scene ) {
+			throw new Error( `Scene has not been initialized.` );
+		}
+		return this._scene;
+	}
+
+	get sceneManager(): SceneManager {
+		if( !this._sceneManager ) {
+			throw new Error( `Environment has not been initialized.` );
+		}
+		return this._sceneManager;
+	}
+
+	/**
+	 * Gets the BabylonJS Engine that is attached to the viewer.
+	 */
+	get engine(): Engine {
+		return this.scene.getEngine();
+	}
+
+	/**
+	 * Gets the {@link VariantInstanceManager} attached to the viewer.
+	 *
+	 * @throws Error if the {@link VariantInstanceManager} has not been initialized.
+	 */
+	get variantInstances(): VariantInstanceManager {
+		if( !this._variantInstances ) {
+			throw Error( `There is no variantInstanceManager.` );
+		}
+		return this._variantInstances;
+	}
+
+	/**
+	 * Gets the {@link AnimationManager} attached to the viewer.
+	 *
+	 * @throws Error if the {@link AnimationManager} has not been initialized.
+	 */
+	get animationManager(): AnimationManager {
+		if( !this._animationManager ) {
+			throw new Error( `There is no animationManager instance.` );
+		}
+		return this._animationManager;
+	}
+
+	/**
+	 * Starts the application. This will
+	 * * load the given "index" JSON file
+	 * * setup the scene with the "scene" JSON file
+	 * * create an (optional) default setup with different variant settings
+	 * * sets up resizing by attaching a debounced version of {@link resize}
+	 *
+	 * @throws Error if any of the files is not found/valid
+	 *
+	 * @emits {@link Event.BOOTSTRAP_START}
+	 * @emits {@link Event.BOOTSTRAP_END}
+	 */
+	public async bootstrap(): Promise<Viewer> {
+		this.broadcastEvent( Event.BOOTSTRAP_START, this );
+		let indexJson;
+		if( isString( this.structureJson ) ) {
+			indexJson = await loadJson<StructureJson>( this.structureJson );
+		} else {
+			indexJson = this.structureJson;
+		}
+		if( !indexJson.scene ) {
+			throw new Error( `No "scene" property found for bootstrapping.` );
+		}
+		// fill spec store
+		SpecStorage.createFromSpec( indexJson );
+		// load scene
+		if( isString( indexJson.scene ) ) {
+			const sceneJson = await loadJson<SceneJson>( indexJson.scene );
+			indexJson.scene = sceneJson;
+		}
+		this._scene = await this.initScene();
+		// create instance manager
+		const rootVariant = await Variant.create( '_', indexJson, this );
+		this._variantInstances = await VariantInstanceManager.create( rootVariant );
+		// create optional default instances
+		if( indexJson.setup ) {
+			if( isString( indexJson.setup ) ) {
+				const setupJson = await loadJson<SetupJson>( indexJson.setup );
+				indexJson.setup = setupJson;
+			}
+			await this.createVariantInstances();
+		}
+		// resize handler
+		window.addEventListener( 'resize', debounce( this.resize.bind( this ), 100 ) );
+		// wait until scene is completely ready
+		await this.scene.whenReadyAsync();
+		// event broadcasting
+		this.broadcastEvent( Event.BOOTSTRAP_END, this );
+		// render loop
+		this.engine.runRenderLoop( () => {
+			this.scene.render();
+		} );
+		return this;
+	}
+
+	// Disabled for now to decrease bundle size.
+	// See https://github.com/Combeenation/3d-viewer/issues/37
+	// /**
+	//  * Enables the BabylonJS DebugLayer. If you pass options, be sure to pass an Object of type `IInspectorOptions`.
+	//  */
+	// public async enableDebugLayer(options?: any) {
+	//  	// @ts-ignore
+	//  	await import(/* webpackChunkName: "debug-inspector" */'@babylonjs/inspector');
+	//  	await this.scene.debugLayer.show(options);
+	//  	return this;
+	// }
+
+	/**
+	 * Destroys all registered {@link VariantInstance}s that are registered
+	 */
+	public destroyVariantInstances(): Viewer {
+		this.variantInstances.all.forEach( variantInstance => {
+			this.variantInstances.destroy( variantInstance.name );
+		} );
+		return this;
+	}
+
+	/**
+	 * Trigger a resize event for the `Engine`
+	 */
+	public resize(): Viewer {
+		this.engine.resize();
+		return this;
+	}
+
+	/**
+	 * A convenience method for directly getting a Node from a {@link VariantInstance} and an {@link Element} by its
+	 * {@link DottedPath}s.
+	 */
+	public async getNode( variantInstanceName: string,
+	                      elementDottedPath: DottedPathArgument,
+	                      nodeDottedPath: DottedPathArgument ): Promise<TransformNode> {
+		const variantInstance = await this.variantInstances.get(variantInstanceName);
+		return variantInstance.getNode( elementDottedPath, nodeDottedPath );
+	}
+
+	/**
+	 * A convenience method for directly getting a Node from a {@link VariantInstance} and an {@link Element} by its
+	 * {@link DottedPath}s.
+	 */
+	public async getMesh( variantInstanceName: string,
+	                      elementDottedPath: DottedPathArgument,
+	                      meshDottedPath: DottedPathArgument ): Promise<Mesh|null> {
+		const variantInstance = await this.variantInstances.get(variantInstanceName);
+		return variantInstance.getMesh( elementDottedPath, meshDottedPath );
+	}
+
+	/**
+	 * Switches the camera
+	 *
+	 * @emits {@link Event.CAMERA_SWITCHED}
+	 */
+	public switchCamera( newCamera: string, reset: boolean = true ): Viewer {
+		const camera = this.scene.getCameraByName( newCamera );
+		if( camera ) {
+			const activeCamera = this.scene.activeCamera;
+			if( activeCamera ) {
+				activeCamera.detachControl( this.engine.getRenderingCanvas()! );
+			}
+			if( reset ) {
+				camera.restoreState();
+			}
+			this.scene.setActiveCameraByName( newCamera );
+			camera.attachControl( this.engine.getRenderingCanvas()! );
+			this.broadcastEvent( Event.CAMERA_SWITCHED, camera );
+		} else {
+			throw new Error( `Given camera "${newCamera}" not found.` );
+		}
+		// TODO: put traceable observers to new camera (@see element)
+		return this;
+	}
+
+	/**
+	 * Moves or animates the active camera to given `placement`.
+	 */
+	public async moveActiveCameraTo( placement: string | PlacementDefinition,
+	                                 animation?: string | AnimationDefinition ): Promise<AnimationInterface> {
+		return this.animationManager.animateToPlacement( this.sceneManager.activeCamera, placement, animation );
+	}
+
+	/**
+	 * Takes a sceenshot the the current scene. The result is a string containing a base64 encoded image
+	 */
+	public screenshot( settings?: ScreenshotSettings ): Promise<string> {
+		return new Promise( ( resolve, reject ) => {
+			if( !this.engine ) {
+				return reject( 'Engine is null' );
+			}
+			if( !this.scene ) {
+				return reject( 'Scene is null' );
+			}
+			this.scene.render();  // in combination with a render target, we need to refresh the scene manually to get the latest view
+			ScreenshotTools.CreateScreenshotUsingRenderTarget(
+				this.engine,
+				this.sceneManager.activeCamera,
+				settings?.size ?? { width: this.canvas.clientWidth, height: this.canvas.clientHeight },
+				resolve,
+				settings?.mimeType ?? 'image/png',
+				settings?.samples ?? 1,
+				settings?.antialiasing ?? false,
+				settings?.fileName ?? 'screenshot.png',
+				settings?.renderSprites ?? false
+			);
+		} );
+	}
+
+	/**
+	 * Calculates the bounding box from all visible meshes on the scene.
+	 */
+	public async calculateBoundingBox(): Promise<Mesh> {
+		if( this.scene.meshes.length === 0 ) {
+			throw new Error( 'There are currently no meshes on the scene.' );
+		}
+		this.scene.render();  // XXX: workaround for BoundingBox not respecting render loop
+		const bbName = '__bounding_box__';
+		
+		const { max, min } = this.scene.meshes.filter( mesh => {
+			const isEnabled = mesh.isEnabled();
+			// ignore the existing bounding box mesh for calculating the current one
+			const isNotBBoxMesh = bbName !== mesh.id;
+			// ignore meshes with invalid bounding infos
+			const hasValidBBoxInfo = mesh.getBoundingInfo().boundingSphere.radius > 0;
+			return isEnabled && isNotBBoxMesh && hasValidBBoxInfo;
+		} ).reduce( ( accBBoxMinMax, curMesh, idx ) => {
+			const bBox = curMesh.getBoundingInfo().boundingBox;
+			// use the first entry in the array as default value and get the resulting maximum/minimum values
+			const max = ( idx === 0 ) ? bBox.maximumWorld : Vector3.Maximize( accBBoxMinMax.max, bBox.maximumWorld )
+			const min = ( idx === 0 ) ? bBox.minimumWorld : Vector3.Minimize( accBBoxMinMax.min, bBox.minimumWorld )
+			return { max, min }
+		}, { max: new Vector3(), min: new Vector3() } );
+
+		let boundingBox = this.scene.getMeshByName( bbName ) as Mesh;
+		if( !boundingBox ) {
+			boundingBox = new Mesh( bbName, this.scene );
+		}
+		boundingBox.setBoundingInfo( new BoundingInfo( min, max ) );
+		return boundingBox;
+	}
+
+	/**
+	 * Focuses the camera to see every visible mesh in scene and tries to optimize wheel precision and panning.
+	 */
+	public async autofocusActiveCamera( settings?: AutofocusSettings ) {
+		const activeCamera = this.scene.activeCamera;
+		if( !activeCamera ) {
+			throw new Error( 'No active camera found when using autofocus feature.' );
+		}
+		if( activeCamera instanceof ArcRotateCamera ) {
+			// calculate some values
+			const boundingBox = await this.calculateBoundingBox();
+			const size = boundingBox.getBoundingInfo().maximum.subtract( boundingBox.getBoundingInfo().minimum );
+			let radius = size.length() * (settings?.radiusFactor ?? 1.5);
+			if( !isFinite( radius ) ) {
+				radius = 1;
+			}
+			// use helper camera to get some default values
+			const helperCamera = new ArcRotateCamera(
+				'__helper_camera__',
+				Math.PI / -2,
+				Math.PI / 2,
+				radius,
+				Vector3.Zero(),
+				this.scene
+			);
+			helperCamera.useFramingBehavior = true;
+			helperCamera.setTarget( boundingBox );
+			// translate values from helper to active camera
+			activeCamera.setTarget( Mesh.Center( [boundingBox] ) );
+			activeCamera.alpha = helperCamera.alpha;
+			activeCamera.beta = helperCamera.beta;
+			activeCamera.minZ = helperCamera.minZ;
+			activeCamera.maxZ = helperCamera.maxZ;
+			activeCamera.radius = helperCamera.radius;
+			activeCamera.lowerRadiusLimit = helperCamera.lowerRadiusLimit;
+			activeCamera.upperRadiusLimit = helperCamera.upperRadiusLimit;
+			if( settings?.adjustWheelPrecision !== false ) {
+				activeCamera.wheelPrecision = helperCamera.wheelPrecision;
+			}
+			if( settings?.adjustPanningSensibility !== false ) {
+				activeCamera.panningSensibility = helperCamera.panningSensibility;
+			}
+			if( settings?.adjustPinchPrecision !== false ) {
+				activeCamera.pinchPrecision = helperCamera.pinchPrecision;
+			}
+			// remove the helper camera
+			helperCamera.dispose();
+		} else {
+			const cameraClsName = activeCamera.getClassName();
+			throw new Error( `Camera of type "${cameraClsName}" is not implemented yet to use autofocus feature.` );
+		}
+	}
+
+	/**
+	 * Resets everything by calling {@link destroy} to clear all references and {@link bootstrap} to setup a clean
+	 * environment
+	 */
+	public async reset(): Promise<Viewer> {
+		await this.destroy();
+		return this.bootstrap();
+	}
+
+	/**
+	 * Destroys
+	 *
+	 * * all {@link VariantInstance}s using {@link destroyVariantInstances}
+	 * * calling `dispose` on the `Engine` and `Scene`
+	 */
+	public destroy(): Viewer {
+		this.destroyVariantInstances();
+		this.scene.dispose();
+		SpecStorage.destroy();
+		return this;
+	}
+
+	/**
+	 * Show coordinate system with given dimension (for debugging purpose).
+	 */
+	public showWorldCoordinates( dimension: number ) {
+		const scene = this.scene;
+		const makeTextPlane = function( text: string, color: string, size: number ) {
+			const dynamicTexture = new DynamicTexture( 'DynamicTexture', 50, scene, true );
+			dynamicTexture.hasAlpha = true;
+			dynamicTexture.drawText( text, 5, 40, 'bold 36px Arial', color, 'transparent', true );
+			const plane = Mesh.CreatePlane( 'TextPlane', size, scene, true );
+			plane.material = new StandardMaterial( 'TextPlaneMaterial', scene );
+			plane.material.backFaceCulling = false;
+			// @ts-ignore
+			plane.material.specularColor = new Color3( 0, 0, 0 );
+			// @ts-ignore
+			plane.material.diffuseTexture = dynamicTexture;
+			return plane;
+		};
+		const axisX = Mesh.CreateLines( 'axisX', [
+			Vector3.Zero(),
+			new Vector3( dimension, 0, 0 ),
+			new Vector3( dimension * 0.95, 0.05 * dimension, 0 ),
+			new Vector3( dimension, 0, 0 ),
+			new Vector3( dimension * 0.95, -0.05 * dimension, 0 )
+		], scene );
+		axisX.color = new Color3( 1, 0, 0 );
+		const xChar = makeTextPlane( 'X', 'red', dimension / 10 );
+		xChar.position = new Vector3( 0.9 * dimension, -0.05 * dimension, 0 );
+		const axisY = Mesh.CreateLines( 'axisY', [
+			Vector3.Zero(),
+			new Vector3( 0, dimension, 0 ),
+			new Vector3( -0.05 * dimension, dimension * 0.95, 0 ),
+			new Vector3( 0, dimension, 0 ),
+			new Vector3( 0.05 * dimension, dimension * 0.95, 0 )
+		], scene );
+		axisY.color = new Color3( 0, 1, 0 );
+		const yChar = makeTextPlane( 'Y', 'green', dimension / 10 );
+		yChar.position = new Vector3( 0, 0.9 * dimension, -0.05 * dimension );
+		const axisZ = Mesh.CreateLines( 'axisZ', [
+			Vector3.Zero(),
+			new Vector3( 0, 0, dimension ),
+			new Vector3( 0, -0.05 * dimension, dimension * 0.95 ),
+			new Vector3( 0, 0, dimension ),
+			new Vector3( 0, 0.05 * dimension, dimension * 0.95 )
+		], scene );
+		axisZ.color = new Color3( 0, 0, 1 );
+		const zChar = makeTextPlane( 'Z', 'blue', dimension / 10 );
+		zChar.position = new Vector3( 0, 0.05 * dimension, 0.9 * dimension );
+	}
+
+	/**
+	 * @emits {@link Event.SCENE_PROCESSING_START}
+	 * @emits {@link Event.SCENE_PROCESSING_END}
+	 */
+	protected async initScene(): Promise<Scene> {
+		const sceneJson = SpecStorage.get<SceneJson>( 'scene' );
+		this.broadcastEvent( Event.SCENE_PROCESSING_START, sceneJson );
+		const engine = new Engine(
+			this.canvas as HTMLCanvasElement,
+			sceneJson.engine?.antialiasing ?? false,
+			sceneJson.engine?.options
+		);
+		const scene = await sceneSetup( engine, sceneJson );
+		if( sceneJson.meshPicking ) {
+			new HighlightLayer( 'default', scene );
+			scene.onPointerPick = ( pointerEvent: PointerEvent, pickInfo: PickingInfo ) => {
+				if( !pickInfo.hit ) {
+					return;
+				}
+				const mesh = pickInfo.pickedMesh;
+				this.broadcastEvent( Event.MESH_PICKED, mesh, mesh?.metadata.element, mesh?.metadata.variant );
+				if( mesh?.metadata.element ) {
+					this.broadcastEvent( Event.ELEMENT_PICKED, mesh.metadata.element );
+				}
+				if( mesh?.metadata.variant ) {
+					if( mesh.metadata.variant.inheritedParameters[Parameter.HIGHLIGHT_ENABLED] ) {
+						mesh.metadata.variant.toggleHighlight();
+					}
+					this.broadcastEvent( Event.VARIANT_PICKED, mesh.metadata.variant );
+				}
+			};
+		}
+		this._sceneManager = await SceneManager.create( scene );
+		this._animationManager = await AnimationManager.create( scene );
+		this.broadcastEvent( Event.SCENE_PROCESSING_END, scene );
+		return scene;
+	}
+
+	/**
+	 * Batch creation of multiple {@link VariantInstance} objects with a {@link SetupJson} object passed
+	 */
+	protected async createVariantInstances(): Promise<VariantInstance[]> {
+		const setupJson = SpecStorage.get<SetupJson>( 'setup' );
+		const instances = [];
+		for( const instanceDefinition of setupJson.instances ) {
+			if( instanceDefinition.lazy ) {
+				this.variantInstances.register( instanceDefinition );
+				continue;
+			}
+			instances.push( await this.variantInstances.create(
+				instanceDefinition.variant,
+				instanceDefinition.name,
+				instanceDefinition.parameters
+			) );
+		}
+		return instances;
+	}
+
 }