@combeenation/3d-viewer 4.2.0 → 5.0.0-alpha1

package/src/api/classes/viewer.ts

@@ -1,3 +1,4 @@
+import { AbstractMesh, IPointerEvent } from '@babylonjs/core';
 import { ArcRotateCamera } from '@babylonjs/core/Cameras/arcRotateCamera';
 import { PickingInfo } from '@babylonjs/core/Collisions/pickingInfo';
 import { BoundingInfo } from '@babylonjs/core/Culling/boundingInfo';
@@ -10,21 +11,23 @@ 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 { WebXRSessionManager } from '@babylonjs/core/XR/webXRSessionManager';
+import { isMeshIncludedInExclusionList } from '../util/structureHelper';
 import { isString } from 'lodash-es';
 import { version } from '../../buildinfo.json';
 import { sceneSetup } from '../internal/sceneSetup';
 import { AnimationManager } from '../manager/animationManager';
+import { GltfExportManager } from '../manager/gltfExportManager';
 import { SceneManager } from '../manager/sceneManager';
 import { VariantInstanceManager } from '../manager/variantInstanceManager';
 import { SpecStorage } from '../store/specStorage';
-import { debounce, loadJson, sleep } from '../util/resourceHelper';
+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
  *
@@ -35,491 +38,590 @@ import { VariantInstance } from './variantInstance';
  * 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();  // CB-6062: 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;
-	}
-
-	public async autofocusActiveCamera( settings?: AutofocusSettings ) {
-		// first check some preconditions
-		const activeCamera = this.scene.activeCamera;
-		if ( !activeCamera ) {
-			throw new Error("No active camera found when using autofocus feature.");
-		}
-		if ( !( activeCamera instanceof ArcRotateCamera ) ) {
-			const cameraClsName = activeCamera.getClassName();
-			throw new Error( `Camera of type "${cameraClsName}" is not implemented yet to use autofocus feature.` );
-		}
-
-		// get bounding box of all visible meshes, this is the base for the autofocus algorithm
-		const boundingBox = await this.calculateBoundingBox();
-
-		// focus the helper camera and set the calculated camera data to the real camera
-		const helperCamera = this.getFocusedHelperCamera( boundingBox, settings )
-		await this.applyFocusedHelperCameraData( activeCamera, helperCamera, settings )
-
-		// remove the helper camera
-		helperCamera.dispose();
-	}
-
-	/**
-	 * 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;
-	}
-
-	/**
-	 * Help function for focusing a helper camera exactly onto the given bounding box
-	 */
-	private getFocusedHelperCamera(boundingBox: Mesh, settings?: AutofocusSettings): ArcRotateCamera {
-		// use helper camera to get some default values and set the values of the real camera accordingly
-		const helperCamera = new ArcRotateCamera(
-			"__helper_camera__",
-			0, // camera angles will be overwritten after the target has been set
-			0,
-			0, // radius will be calculated, so we can set to 0 here
-			Vector3.Zero(),
-			this.scene
-		);
-		// this is required for automatically calculating the `lowerRadiusLimit`, so that we don't "dive" into meshes
-		// see https://doc.babylonjs.com/divingDeeper/behaviors/cameraBehaviors#framing-behavior
-		helperCamera.useFramingBehavior = true;
-
-		// `minZ` is the camera distance beyond which the mesh will be clipped
-		// this should be very low, but can't be zero
-		// a good value seems to be 1% of the bounding box size (= radius), whereas the value shouldn't go above 1, which is also the default value
-		const radius = boundingBox.getBoundingInfo().boundingSphere.radius;
-		helperCamera.minZ = Math.min(radius/100, 1);
-
-		// set desired camera data, these won't be changed by the autofocus function!
-		// default values should focus the element exactly from the front (= XY Plane)
-		helperCamera.setTarget(boundingBox, true);
-		helperCamera.alpha = ( settings?.alpha ?? - 90 ) * ( Math.PI / 180 );
-		helperCamera.beta = ( settings?.beta ?? 90 ) * ( Math.PI / 180 );
-
-		// finally zoom to the bounding box
-		// also apply a zoom factor, this adjusts the borders around the model in the viewport
-		helperCamera.zoomOnFactor = settings?.radiusFactor || 1;
-		helperCamera.zoomOn( [boundingBox], true );
-
-		return helperCamera;
-	}
-
-	/**
-	 * Help function for applying the relevant data of the focused helper camera to the real camera
-	 */
-	private async applyFocusedHelperCameraData(activeCamera: ArcRotateCamera, helperCamera: ArcRotateCamera, settings?: AutofocusSettings) {
-		// limits
-		activeCamera.minZ = helperCamera.minZ;
-		activeCamera.maxZ = helperCamera.maxZ;
-		activeCamera.lowerRadiusLimit = helperCamera.lowerRadiusLimit;
-		activeCamera.upperRadiusLimit = helperCamera.upperRadiusLimit;
-
-		// additional settings
-		if( settings?.adjustWheelPrecision !== false ) {
-			activeCamera.wheelPrecision = helperCamera.wheelPrecision;
-		}
-		if( settings?.adjustPanningSensibility !== false ) {
-			activeCamera.panningSensibility = helperCamera.panningSensibility;
-		}
-		if( settings?.adjustPinchPrecision !== false ) {
-			activeCamera.pinchPrecision = helperCamera.pinchPrecision;
-		}
-
-		// finally move the camera
-		// do this at last, so that all camera settings are already considered
-		const newCameraPosition: PlacementDefinition = {
-			alpha: helperCamera.alpha,
-			beta: helperCamera.beta,
-			radius: helperCamera.radius,
-			target: helperCamera.target
-		}
-		await this.animationManager.animateToPlacement(activeCamera, newCameraPosition, settings?.animation)
-	}
-}
+  protected _scene: Scene | null = null;
+
+  protected _animationManager: AnimationManager | null = null;
+
+  protected _sceneManager: SceneManager | null = null;
+
+  protected _gltfExportManager: GltfExportManager | null = null;
+
+  protected _variantInstances: VariantInstanceManager | null = null;
+
+  // default value is `true` ATM for compatibility reasons
+  // in the future material cloning should be the edge case
+  protected _cloneMaterialsOnMutation: boolean = true;
+
+  protected _isRenderLoopPaused: boolean = false;
+
+  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;
+  }
+
+  /**
+   * Gets the {@link SceneManager} attached to the viewer.
+   *
+   * @throws Error if the {@link SceneManager} has not been initialized.
+   */
+  get sceneManager(): SceneManager {
+    if (!this._sceneManager) {
+      throw new Error(`SceneManager has not been initialized.`);
+    }
+    return this._sceneManager;
+  }
+
+  /**
+   * Gets the {@link GltfExportManager} attached to the viewer.
+   *
+   * @throws Error if the {@link GltfExportManager} has not been initialized.
+   */
+  get gltfExportManager(): GltfExportManager {
+    if (!this._gltfExportManager) {
+      throw new Error(`GltfExportManager has not been initialized.`);
+    }
+    return this._gltfExportManager;
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * Gets the `cloneMaterialsOnMutation` flag, as defined in the spec
+   */
+  get cloneMaterialsOnMutation(): boolean {
+    return this._cloneMaterialsOnMutation;
+  }
+
+  /**
+   * 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();
+    }
+    // create gltf export manager
+    this._gltfExportManager = await GltfExportManager.create(this);
+    // 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(() => {
+      if (!this._isRenderLoopPaused) this.scene.render();
+    });
+    return this;
+  }
+
+  /**
+   * Enables the BabylonJS [Inspector](https://doc.babylonjs.com/toolsAndResources/tools/inspector).\
+   * Due to the enormous additional package size of the inspector, this feature is only available in development builds.
+   */
+  public async enableDebugLayer(options?: IInspectorOptions) {
+    if (process.env.NODE_ENV?.toLowerCase().includes('dev')) {
+      await import(/* webpackChunkName: "debug-inspector" */ '@babylonjs/inspector');
+      await this.scene.debugLayer.show(options);
+    } else {
+      console.warn('BabylonJS inspector is not supported in production builds!');
+    }
+  }
+
+  /**
+   * 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
+      );
+    });
+  }
+
+  /**
+   * Checks whether the browser is capable of handling XR.
+   */
+  public async isBrowserARCapable(): Promise<boolean> {
+    return await WebXRSessionManager.IsSessionSupportedAsync('immersive-ar');
+  }
+
+  /**
+   * Calculates the bounding box from all visible meshes on the scene.
+   */
+  public async calculateBoundingBox(excludeGeometry?: ExcludedGeometry): Promise<Mesh> {
+    if (this.scene.meshes.length === 0) {
+      throw new Error('There are currently no meshes on the scene.');
+    }
+    this.scene.render(); // CB-6062: 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;
+        // ignore excluded meshes
+        const isExcluded = excludeGeometry ? isMeshIncludedInExclusionList(mesh as Mesh, excludeGeometry) : false;
+        return isEnabled && isNotBBoxMesh && hasValidBBoxInfo && !isExcluded;
+      })
+      .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) {
+    // first check some preconditions
+    const activeCamera = this.scene.activeCamera;
+    if (!activeCamera) {
+      throw new Error('No active camera found when using autofocus feature.');
+    }
+    if (!(activeCamera instanceof ArcRotateCamera)) {
+      const cameraClsName = activeCamera.getClassName();
+      throw new Error(`Camera of type "${cameraClsName}" is not implemented yet to use autofocus feature.`);
+    }
+
+    // get bounding box of all visible meshes, this is the base for the autofocus algorithm
+    const boundingBox = await this.calculateBoundingBox(settings?.exclude);
+
+    // focus the helper camera and set the calculated camera data to the real camera
+    const helperCamera = this.getFocusedHelperCamera(boundingBox, settings);
+    await this.applyFocusedHelperCameraData(activeCamera, helperCamera, settings);
+
+    // remove the helper camera
+    helperCamera.dispose();
+  }
+
+  /**
+   * 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,
+      false
+    );
+    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,
+      false
+    );
+    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,
+      false
+    );
+    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);
+  }
+
+  /**
+   * Pause render loop.
+   */
+  public pauseRendering() {
+    this._isRenderLoopPaused = true;
+  }
+
+  /**
+   * Resume render loop when paused.
+   */
+  public resumeRendering() {
+    this._isRenderLoopPaused = false;
+  }
+
+  /**
+   * @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: IPointerEvent, 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);
+    if (sceneJson.cloneMaterialsOnMutation !== undefined) {
+      this._cloneMaterialsOnMutation = sceneJson.cloneMaterialsOnMutation;
+    }
+    if (sceneJson.useRightHandedSystem !== undefined) {
+      scene.useRightHandedSystem = sceneJson.useRightHandedSystem;
+    }
+    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;
+  }
+
+  /**
+   * Help function for focusing a helper camera exactly onto the given bounding box
+   */
+  private getFocusedHelperCamera(boundingBox: Mesh, settings?: AutofocusSettings): ArcRotateCamera {
+    // use helper camera to get some default values and set the values of the real camera accordingly
+    const helperCamera = new ArcRotateCamera(
+      '__helper_camera__',
+      0, // camera angles will be overwritten after the target has been set
+      0,
+      0, // radius will be calculated, so we can set to 0 here
+      Vector3.Zero(),
+      this.scene
+    );
+    // this is required for automatically calculating the `lowerRadiusLimit`, so that we don't "dive" into meshes
+    // see https://doc.babylonjs.com/divingDeeper/behaviors/cameraBehaviors#framing-behavior
+    helperCamera.useFramingBehavior = true;
+
+    // `minZ` is the camera distance beyond which the mesh will be clipped
+    // this should be very low, but can't be zero
+    // a good value seems to be 1% of the bounding box size (= radius), whereas the value shouldn't go above 1, which is also the default value
+    const radius = boundingBox.getBoundingInfo().boundingSphere.radius;
+    helperCamera.minZ = Math.min(radius / 100, 1);
+
+    // set desired camera data, these won't be changed by the autofocus function!
+    // default values should focus the element exactly from the front (= XY Plane)
+    helperCamera.setTarget(boundingBox, true);
+    helperCamera.alpha = (settings?.alpha ?? -90) * (Math.PI / 180);
+    helperCamera.beta = (settings?.beta ?? 90) * (Math.PI / 180);
+
+    // finally zoom to the bounding box
+    // also apply a zoom factor, this adjusts the borders around the model in the viewport
+    helperCamera.zoomOnFactor = settings?.radiusFactor || 1;
+    helperCamera.zoomOn([boundingBox], true);
+
+    return helperCamera;
+  }
+
+  /**
+   * Help function for applying the relevant data of the focused helper camera to the real camera
+   */
+  private async applyFocusedHelperCameraData(
+    activeCamera: ArcRotateCamera,
+    helperCamera: ArcRotateCamera,
+    settings?: AutofocusSettings
+  ) {
+    // limits
+    activeCamera.minZ = helperCamera.minZ;
+    activeCamera.maxZ = helperCamera.maxZ;
+    activeCamera.lowerRadiusLimit = helperCamera.lowerRadiusLimit;
+    activeCamera.upperRadiusLimit = helperCamera.upperRadiusLimit;
+
+    // additional settings
+    if (settings?.adjustWheelPrecision !== false) {
+      activeCamera.wheelPrecision = helperCamera.wheelPrecision;
+    }
+    if (settings?.adjustPanningSensibility !== false) {
+      activeCamera.panningSensibility = helperCamera.panningSensibility;
+    }
+    if (settings?.adjustPinchPrecision !== false) {
+      activeCamera.pinchPrecision = helperCamera.pinchPrecision;
+    }
+
+    // finally move the camera
+    // do this at last, so that all camera settings are already considered
+    const newCameraPosition: PlacementDefinition = {
+      alpha: helperCamera.alpha,
+      beta: helperCamera.beta,
+      radius: helperCamera.radius,
+      target: helperCamera.target,
+    };
+    await this.animationManager.animateToPlacement(activeCamera, newCameraPosition, settings?.animation);
+  }
+}