@combeenation/3d-viewer 7.1.1 → 7.1.2

package/src/api/classes/viewer.ts

@@ -1,744 +1,760 @@
-import buildInfo from '../../buildinfo.json';
-import { sceneSetup } from '../internal/sceneSetup';
-import { AnimationManager } from '../manager/animationManager';
-import { GltfExportManager } from '../manager/gltfExportManager';
-import { SceneManager } from '../manager/sceneManager';
-import { TagManager } from '../manager/tagManager';
-import { VariantInstanceManager } from '../manager/variantInstanceManager';
-import { SpecStorage } from '../store/specStorage';
-import { backgroundDomeName, envHelperMetadataName } from '../util/babylonHelper';
-import { debounce, loadJavascript, loadJson } from '../util/resourceHelper';
-import { getCustomCbnBabylonLoaderPlugin } from '../util/sceneLoaderHelper';
-import { replaceDots } from '../util/stringHelper';
-import { isMeshIncludedInExclusionList } from '../util/structureHelper';
-import { AnimationInterface } from './animationInterface';
-import { Event } from './event';
-import { EventBroadcaster } from './eventBroadcaster';
-import { Parameter } from './parameter';
-import { VariantInstance } from './variantInstance';
-import { ArcRotateCamera } from '@babylonjs/core/Cameras/arcRotateCamera';
-import { PickingInfo } from '@babylonjs/core/Collisions/pickingInfo';
-import { BoundingInfo } from '@babylonjs/core/Culling/boundingInfo';
-import { DebugLayer } from '@babylonjs/core/Debug/debugLayer';
-import { Engine } from '@babylonjs/core/Engines/engine';
-import { IPointerEvent } from '@babylonjs/core/Events/deviceInputEvents';
-import { EnvironmentHelper } from '@babylonjs/core/Helpers/environmentHelper';
-import { PhotoDome } from '@babylonjs/core/Helpers/photoDome';
-import { HighlightLayer } from '@babylonjs/core/Layers/highlightLayer';
-import { ISceneLoaderPlugin, SceneLoader } from '@babylonjs/core/Loading/sceneLoader';
-import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
-import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
-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 { WebXRSessionManager } from '@babylonjs/core/XR/webXRSessionManager';
-import { Scene } from '@babylonjs/core/scene';
-import { isArray, isString } from 'lodash-es';
-
-/**
- * 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 {
-  public static readonly BOUNDING_BOX_NAME = '__bounding_box__';
-
-  protected _scene: Scene | null = null;
-
-  protected _animationManager: AnimationManager | null = null;
-
-  protected _sceneManager: SceneManager | null = null;
-
-  protected _tagManager: TagManager | null = null;
-
-  protected _gltfExportManager: GltfExportManager | null = null;
-
-  protected _variantInstances: VariantInstanceManager | null = null;
-
-  // defaults to `false` as material cloning should be the edge case
-  protected _cloneMaterialsOnMutation: boolean = false;
-
-  protected _isRenderLoopPaused: boolean = false;
-
-  protected _inspectorLoaded: boolean = false;
-
-  protected _nodeNamingStrategyHandler: NodeNamingStrategyHandler | null = null;
-
-  static version = buildInfo.version;
-
-  // these are constants for calculating the camera settings, depending on the bounding box size of the meshes to zoom
-  // the algorithms and constant values are directly taken from the Babylon.js repository
-  private static readonly _autofocusConstants = {
-    minZ: 100,
-    wheelPrecision: 100,
-    panningSensibility: 5000,
-    pinchPrecision: 200,
-  };
-
-  /**
-   * Help function for automatically creating a valid Spec from a list of variant names and dedicated GLB/babylon URLs.
-   * This data is most likely coming from babylon assets from the Combeenation system but other sources are also valid.
-   */
-  public static generateSpec(genData: SpecGenerationData[]): AutoSpecStructureJson {
-    // dots in the variant name indicate inheritance, but this should not be the case for an auto-generated spec
-    // therefore dots are exchanged with slashes
-    const safeGenData: SpecGenerationData[] = genData.map(data => ({ ...data, name: replaceDots(data.name) }));
-
-    const spec: AutoSpecStructureJson = {
-      // common scene settings as suggested in the viewer docs
-      scene: {
-        engine: {
-          antialiasing: true,
-          options: {
-            preserveDrawingBuffer: true,
-            stencil: true,
-            xrCompatible: false,
-          },
-        },
-        scene: {
-          globals: {},
-        },
-      },
-      setup: {
-        // create one instance for each input entry
-        // name and variant are named accordingly from the input, instance will be hidden by default and lazy loading
-        // is activated
-        instances: safeGenData.map(instanceData => ({
-          name: instanceData.name,
-          variant: instanceData.name,
-          lazy: true,
-          parameters: {
-            [Parameter.VISIBLE]: false,
-          },
-        })),
-      },
-      // variants definition is also mapped to the input array, using the name as key and url as glTF source
-      // no elements are created here, since this should be done automatically from the system
-      // => create one element which contains all root nodes of the imported 3d file (GLB or babylon)
-      variants: safeGenData.reduce((accVariants, curVariant) => {
-        accVariants[curVariant.name] = {
-          glTF: curVariant.url,
-        };
-
-        return accVariants;
-      }, {} as { [id: string]: StructureJson }),
-    };
-
-    return spec;
-  }
-
-  /**
-   * Constructor
-   */
-  public constructor(public readonly canvas: HTMLCanvasElement, protected structureJson: string | StructureJson) {
-    super();
-    this._tagManager = new TagManager(this);
-    this._nodeNamingStrategyHandler = (node, payload) => {
-      const suffix: string[] = [];
-      if (payload.variant.elements.length > 0) {
-        const nodeElements = payload.variant.elements.filter(
-          e => e.nodesFlat.filter(n => n.metadata?.cloneSource?.id === node.id).length > 0
-        );
-        if (nodeElements.length > 0) {
-          suffix.push(payload.variantParameterizable.name);
-        }
-      }
-      const variantInstances = this.variantInstances.allWithVariantName(payload.variant.name);
-      if (variantInstances.length > 0) {
-        suffix.push(payload.variantInstance.name);
-      }
-      const originalName = node.metadata?.originalName || node.name;
-      return [originalName, ...suffix.filter(s => !!s)].join('.');
-    };
-  }
-
-  /**
-   * Gets the Babylon.js 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 Babylon.js 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;
-  }
-
-  get tagManager(): TagManager {
-    if (!this._tagManager) {
-      throw new Error(`There is no tagManager instance.`);
-    }
-    return this._tagManager;
-  }
-
-  /**
-   * Gets the `cloneMaterialsOnMutation` flag, as defined in the spec
-   */
-  get cloneMaterialsOnMutation(): boolean {
-    return this._cloneMaterialsOnMutation;
-  }
-
-  /**
-   * Gets the strategy handler for naming cloned nodes.
-   */
-  get nodeNamingStrategyHandler(): NodeNamingStrategyHandler {
-    if (!this._nodeNamingStrategyHandler) {
-      throw new Error(`The NodeNamingStrategyHandler has not been registered yet.`);
-    }
-    return this._nodeNamingStrategyHandler;
-  }
-
-  /**
-   * Sets the strategy handler for naming cloned nodes.\
-   * Check the docs of the tag managers [renaming](https://3dviewer.docs.combeenation.com/pages/documentation/Tag-Manager.html#uniqueness-of-node-and-tag-names)
-   * chapter for further details.
-   */
-  set nodeNamingStrategyHandler(value: NodeNamingStrategyHandler) {
-    if (!value || typeof value !== 'function') {
-      throw new Error(`The NodeNamingStrategyHandler is not a callable function.`);
-    }
-    this._nodeNamingStrategyHandler = value;
-  }
-
-  /**
-   * 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(tagManagerParameterValues?: TagManagerParameterValue[]): 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);
-    // init custom loader plugin
-    this.initCbnBabylonLoaderPlugin();
-    // load scene
-    if (isString(indexJson.scene)) {
-      const sceneJson = await loadJson<SceneJson>(indexJson.scene);
-      indexJson.scene = sceneJson;
-    }
-    this._scene = await this.initScene();
-    // create instance manager
-    this._variantInstances = await VariantInstanceManager.create(this);
-    // create optional default instances
-    if (indexJson.setup) {
-      if (isString(indexJson.setup)) {
-        const setupJson = await loadJson<SetupJson>(indexJson.setup);
-        indexJson.setup = setupJson;
-      }
-      await this.createVariantInstances(tagManagerParameterValues);
-    }
-    this.broadcastEvent(Event.VARIANT_INSTANCES_READY, this);
-    // 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 Babylon.js [Inspector](https://doc.babylonjs.com/toolsAndResources/tools/inspector).\
-   * Due to the additional size of the inspector, the CDN version is used instead of shipping the required code with
-   * the viewer.\
-   * This means that the code will be downloaded only when needed and calling `enableDebugLayer` can take a little while
-   * depending on your internet connection etc.
-   */
-  public async enableDebugLayer(options?: IInspectorOptions) {
-    if (!this._inspectorLoaded) {
-      // CDN version of inspector requires the Babylon.js core to be available as CDN module as well
-      await loadJavascript('https://cdn.jsdelivr.net/npm/babylonjs@5.6.0/babylon.min.js');
-
-      DebugLayer.InspectorURL =
-        'https://cdn.jsdelivr.net/npm/babylonjs-inspector@5.6.0/babylon.inspector.bundle.max.min.js';
-
-      this._inspectorLoaded = true;
-    }
-
-    await this.scene.debugLayer.show(options);
-  }
-
-  /**
-   * 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?: ExcludedGeometryList): 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 { max, min } = this.scene.meshes
-      .filter(mesh => {
-        const isEnabled = mesh.isEnabled();
-        // ignore the existing bounding box mesh for calculating the current one
-        const isNotBBoxMesh = Viewer.BOUNDING_BOX_NAME !== 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(Viewer.BOUNDING_BOX_NAME) as Mesh;
-    if (!boundingBox) {
-      boundingBox = new Mesh(Viewer.BOUNDING_BOX_NAME, 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.`);
-    }
-
-    let exclude = settings?.exclude || [];
-
-    // Exclude shown photo dome or environment helper from bounding box calculation
-    const photoDome = this.scene.getNodeByName(backgroundDomeName) as undefined | PhotoDome;
-    const photoDomeMeshes = photoDome?.getChildMeshes();
-    if (photoDomeMeshes?.length) {
-      exclude = [...exclude, ...photoDomeMeshes];
-    }
-
-    const envHelper = this.scene.metadata?.[envHelperMetadataName] as undefined | EnvironmentHelper;
-    if (envHelper?.rootMesh) {
-      exclude = [...exclude, envHelper.rootMesh];
-    }
-
-    // get bounding box of all visible meshes, this is the base for the autofocus algorithm
-    const boundingBox = await this.calculateBoundingBox(exclude);
-
-    const radius = boundingBox.getBoundingInfo().boundingSphere.radius;
-    const center = boundingBox.getBoundingInfo().boundingSphere.center;
-    const diameter = radius * 2;
-
-    // set lower radius limit on edge of bounding sphere to make sure that we can't dive into the meshes
-    activeCamera.lowerRadiusLimit = radius;
-
-    // additional settings
-    // constants for division are taken directly from Babylon.js repository
-    activeCamera.minZ = Math.min(radius / Viewer._autofocusConstants.minZ, 1);
-    if (settings?.adjustWheelPrecision !== false) {
-      activeCamera.wheelPrecision = Viewer._autofocusConstants.wheelPrecision / radius;
-    }
-    if (settings?.adjustPanningSensibility !== false) {
-      activeCamera.panningSensibility = Viewer._autofocusConstants.panningSensibility / diameter;
-    }
-    if (settings?.adjustPinchPrecision !== false) {
-      activeCamera.pinchPrecision = Viewer._autofocusConstants.pinchPrecision / radius;
-    }
-
-    const radiusFactor = settings?.radiusFactor ?? 1.5;
-    const alpha = (settings?.alpha ?? -90) * (Math.PI / 180);
-    const beta = (settings?.beta ?? 90) * (Math.PI / 180);
-
-    const newCameraPosition = {
-      alpha: alpha,
-      beta: beta,
-      // this calculation is a bit "simplified", as it doesn't consider the viewport ratio or the frustum angle
-      // but it's also done this way in the Babylon.js repository, so it should be fine for us
-      radius: diameter * radiusFactor,
-      target: center,
-    };
-
-    await this.animationManager.animateToPlacement(activeCamera, newCameraPosition, settings?.animation);
-  }
-
-  /**
-   * Resets everything by calling {@link destroy} to clear all references and {@link bootstrap} to setup a clean
-   * environment
-   */
-  public async reset(tagManagerParameterValues: TagManagerParameterValue[]): Promise<Viewer> {
-    await this.destroy();
-    return this.bootstrap(tagManagerParameterValues);
-  }
-
-  /**
-   * 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;
-      (plane.material as StandardMaterial).specularColor = new Color3(0, 0, 0);
-      (plane.material as StandardMaterial).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;
-    }
-    // register observers for tag manager
-    this.tagManager.registerNewTransformNodeObservers(scene);
-    this.broadcastEvent(Event.SCENE_PROCESSING_END, scene);
-    return scene;
-  }
-
-  /**
-   * Register custom file loader for babylon files which adds "missing-material" metadata to meshes which reference
-   * materials that are not present in the `materials` section of the given babylon file.
-   *
-   * Required for babylon files & materials loaded from "Combeenation configurator assets".
-   */
-  protected initCbnBabylonLoaderPlugin() {
-    const previousLoaderPlugin = SceneLoader.GetPluginForExtension('babylon') as ISceneLoaderPlugin;
-    const customLoaderPlugin = getCustomCbnBabylonLoaderPlugin(previousLoaderPlugin);
-    SceneLoader.RegisterPlugin(customLoaderPlugin);
-  }
-
-  /**
-   * Batch creation of multiple {@link VariantInstance} objects with a {@link SetupJson} object passed
-   */
-  protected async createVariantInstances(
-    tagManagerParameterValues?: TagManagerParameterValue[]
-  ): Promise<VariantInstance[]> {
-    const setupJson = SpecStorage.get<SetupJson>('setup');
-    const instances: VariantInstance[] = [];
-    for (const instanceDefinition of setupJson.instances) {
-      if (isArray(tagManagerParameterValues)) {
-        instanceDefinition.tagManagerParameterValues = tagManagerParameterValues;
-      }
-      // don't create the instance right away if `lazy` is set, register it for later creation (on first usage) instead
-      // however if the variant should be `visible` by default, `lazy` loading doesn't make sense and should therefore
-      // be overruled by the `visible` flag
-      if (instanceDefinition.lazy && instanceDefinition.parameters?.visible !== true) {
-        this.variantInstances.register(instanceDefinition);
-        continue;
-      }
-      const instance = await this.variantInstances.create(
-        instanceDefinition.variant,
-        instanceDefinition.name,
-        instanceDefinition.parameters,
-        instanceDefinition.tagManagerParameterValues
-      );
-      instances.push(instance);
-    }
-    return instances;
-  }
-}
+import buildInfo from '../../buildinfo.json';
+import { sceneSetup } from '../internal/sceneSetup';
+import { AnimationManager } from '../manager/animationManager';
+import { GltfExportManager } from '../manager/gltfExportManager';
+import { SceneManager } from '../manager/sceneManager';
+import { TagManager } from '../manager/tagManager';
+import { VariantInstanceManager } from '../manager/variantInstanceManager';
+import { SpecStorage } from '../store/specStorage';
+import { backgroundDomeName, envHelperMetadataName } from '../util/babylonHelper';
+import { debounce, loadJavascript, loadJson } from '../util/resourceHelper';
+import { getCustomCbnBabylonLoaderPlugin } from '../util/sceneLoaderHelper';
+import { replaceDots } from '../util/stringHelper';
+import { isMeshIncludedInExclusionList } from '../util/structureHelper';
+import { AnimationInterface } from './animationInterface';
+import { Event } from './event';
+import { EventBroadcaster } from './eventBroadcaster';
+import { Parameter } from './parameter';
+import { VariantInstance } from './variantInstance';
+import { ArcRotateCamera } from '@babylonjs/core/Cameras/arcRotateCamera';
+import { PickingInfo } from '@babylonjs/core/Collisions/pickingInfo';
+import { BoundingInfo } from '@babylonjs/core/Culling/boundingInfo';
+import { DebugLayer } from '@babylonjs/core/Debug/debugLayer';
+import { Engine } from '@babylonjs/core/Engines/engine';
+import { IPointerEvent } from '@babylonjs/core/Events/deviceInputEvents';
+import { EnvironmentHelper } from '@babylonjs/core/Helpers/environmentHelper';
+import { PhotoDome } from '@babylonjs/core/Helpers/photoDome';
+import { HighlightLayer } from '@babylonjs/core/Layers/highlightLayer';
+import { ISceneLoaderPlugin, SceneLoader } from '@babylonjs/core/Loading/sceneLoader';
+import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
+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 { WebXRSessionManager } from '@babylonjs/core/XR/webXRSessionManager';
+import { Scene } from '@babylonjs/core/scene';
+import { isArray, isString } from 'lodash-es';
+
+/**
+ * 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 {
+  public static readonly BOUNDING_BOX_NAME = '__bounding_box__';
+
+  protected _scene: Scene | null = null;
+
+  protected _animationManager: AnimationManager | null = null;
+
+  protected _sceneManager: SceneManager | null = null;
+
+  protected _tagManager: TagManager | null = null;
+
+  protected _gltfExportManager: GltfExportManager | null = null;
+
+  protected _variantInstances: VariantInstanceManager | null = null;
+
+  // defaults to `false` as material cloning should be the edge case
+  protected _cloneMaterialsOnMutation: boolean = false;
+
+  protected _isRenderLoopPaused: boolean = false;
+
+  protected _inspectorLoaded: boolean = false;
+
+  protected _nodeNamingStrategyHandler: NodeNamingStrategyHandler | null = null;
+
+  static version = buildInfo.version;
+
+  // these are constants for calculating the camera settings, depending on the bounding box size of the meshes to zoom
+  // the algorithms and constant values are directly taken from the Babylon.js repository
+  private static readonly _autofocusConstants = {
+    minZ: 100,
+    wheelPrecision: 100,
+    panningSensibility: 5000,
+    pinchPrecision: 200,
+  };
+
+  /**
+   * Help function for automatically creating a valid Spec from a list of variant names and dedicated GLB/babylon URLs.
+   * This data is most likely coming from babylon assets from the Combeenation system but other sources are also valid.
+   */
+  public static generateSpec(genData: SpecGenerationData[]): AutoSpecStructureJson {
+    // dots in the variant name indicate inheritance, but this should not be the case for an auto-generated spec
+    // therefore dots are exchanged with slashes
+    const safeGenData: SpecGenerationData[] = genData.map(data => ({ ...data, name: replaceDots(data.name) }));
+
+    const spec: AutoSpecStructureJson = {
+      // common scene settings as suggested in the viewer docs
+      scene: {
+        engine: {
+          antialiasing: true,
+          options: {
+            preserveDrawingBuffer: true,
+            stencil: true,
+            xrCompatible: false,
+          },
+        },
+        scene: {
+          globals: {},
+        },
+      },
+      setup: {
+        // create one instance for each input entry
+        // name and variant are named accordingly from the input, instance will be hidden by default and lazy loading
+        // is activated
+        instances: safeGenData.map(instanceData => ({
+          name: instanceData.name,
+          variant: instanceData.name,
+          lazy: true,
+          parameters: {
+            [Parameter.VISIBLE]: false,
+          },
+        })),
+      },
+      // variants definition is also mapped to the input array, using the name as key and url as glTF source
+      // no elements are created here, since this should be done automatically from the system
+      // => create one element which contains all root nodes of the imported 3d file (GLB or babylon)
+      variants: safeGenData.reduce((accVariants, curVariant) => {
+        accVariants[curVariant.name] = {
+          glTF: curVariant.url,
+        };
+
+        return accVariants;
+      }, {} as { [id: string]: StructureJson }),
+    };
+
+    return spec;
+  }
+
+  /**
+   * Constructor
+   */
+  public constructor(public readonly canvas: HTMLCanvasElement, protected structureJson: string | StructureJson) {
+    super();
+    this._tagManager = new TagManager(this);
+    this._nodeNamingStrategyHandler = (node, payload) => {
+      const suffix: string[] = [];
+      // (1) instance part
+      const variantInstances = this.variantInstances.allWithVariantName(payload.variant.name);
+      if (variantInstances.length > 0) {
+        suffix.push(payload.variantInstance.name);
+      }
+      // (2) element part
+      if (payload.variant.elements.length > 0) {
+        const nodeElements = payload.variant.elements.filter(
+          e => e.nodesFlat.filter(n => n.metadata?.cloneSource?.id === node.id).length > 0
+        );
+        if (nodeElements.length > 0) {
+          suffix.push(payload.variantParameterizable.name);
+        }
+      }
+      // (3) merge together
+      const originalName = node.metadata?.originalName || node.name;
+      return [originalName, ...suffix.filter(s => !!s)].join('.');
+    };
+  }
+
+  /**
+   * Gets the Babylon.js 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 Babylon.js 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;
+  }
+
+  get tagManager(): TagManager {
+    if (!this._tagManager) {
+      throw new Error(`There is no tagManager instance.`);
+    }
+    return this._tagManager;
+  }
+
+  /**
+   * Gets the `cloneMaterialsOnMutation` flag, as defined in the spec
+   */
+  get cloneMaterialsOnMutation(): boolean {
+    return this._cloneMaterialsOnMutation;
+  }
+
+  /**
+   * Gets the strategy handler for naming cloned nodes.
+   */
+  get nodeNamingStrategyHandler(): NodeNamingStrategyHandler {
+    if (!this._nodeNamingStrategyHandler) {
+      throw new Error(`The NodeNamingStrategyHandler has not been registered yet.`);
+    }
+    return this._nodeNamingStrategyHandler;
+  }
+
+  /**
+   * Sets the strategy handler for naming cloned nodes.\
+   * Check the docs of the tag managers [renaming](https://3dviewer.docs.combeenation.com/pages/documentation/Tag-Manager.html#uniqueness-of-node-and-tag-names)
+   * chapter for further details.
+   */
+  set nodeNamingStrategyHandler(value: NodeNamingStrategyHandler) {
+    if (!value || typeof value !== 'function') {
+      throw new Error(`The NodeNamingStrategyHandler is not a callable function.`);
+    }
+    this._nodeNamingStrategyHandler = value;
+  }
+
+  /**
+   * 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(tagManagerParameterValues?: TagManagerParameterValue[]): 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);
+    // init custom loader plugin
+    this.initCbnBabylonLoaderPlugin();
+    // load scene
+    if (isString(indexJson.scene)) {
+      const sceneJson = await loadJson<SceneJson>(indexJson.scene);
+      indexJson.scene = sceneJson;
+    }
+    this._scene = await this.initScene();
+    // create instance manager
+    this._variantInstances = await VariantInstanceManager.create(this);
+    // create optional default instances
+    if (indexJson.setup) {
+      if (isString(indexJson.setup)) {
+        const setupJson = await loadJson<SetupJson>(indexJson.setup);
+        indexJson.setup = setupJson;
+      }
+      this.printInstanceDefinitions(indexJson.setup);
+      await this.createVariantInstances(tagManagerParameterValues);
+    }
+    this.broadcastEvent(Event.VARIANT_INSTANCES_READY, this);
+    // 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 Babylon.js [Inspector](https://doc.babylonjs.com/toolsAndResources/tools/inspector).\
+   * Due to the additional size of the inspector, the CDN version is used instead of shipping the required code with
+   * the viewer.\
+   * This means that the code will be downloaded only when needed and calling `enableDebugLayer` can take a little while
+   * depending on your internet connection etc.
+   */
+  public async enableDebugLayer(options?: IInspectorOptions) {
+    if (!this._inspectorLoaded) {
+      // CDN version of inspector requires the Babylon.js core to be available as CDN module as well
+      await loadJavascript('https://cdn.jsdelivr.net/npm/babylonjs@5.6.0/babylon.min.js');
+
+      DebugLayer.InspectorURL =
+        'https://cdn.jsdelivr.net/npm/babylonjs-inspector@5.6.0/babylon.inspector.bundle.max.min.js';
+
+      this._inspectorLoaded = true;
+    }
+
+    await this.scene.debugLayer.show(options);
+  }
+
+  /**
+   * 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?: ExcludedGeometryList): 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 { max, min } = this.scene.meshes
+      .filter(mesh => {
+        const isEnabled = mesh.isEnabled();
+        // ignore the existing bounding box mesh for calculating the current one
+        const isNotBBoxMesh = Viewer.BOUNDING_BOX_NAME !== mesh.id;
+        // ignore meshes with invalid bounding infos
+        const hasValidBBoxInfo = mesh.getBoundingInfo().boundingSphere.radius > 0;
+        // ignore meshes with infinite distance, typically these are sky boxes
+        const hasInfiniteDistance = mesh.infiniteDistance;
+        // ignore excluded meshes
+        const isExcluded = excludeGeometry ? isMeshIncludedInExclusionList(mesh as Mesh, excludeGeometry) : false;
+        return isEnabled && isNotBBoxMesh && hasValidBBoxInfo && !hasInfiniteDistance && !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(Viewer.BOUNDING_BOX_NAME) as Mesh;
+    if (!boundingBox) {
+      boundingBox = new Mesh(Viewer.BOUNDING_BOX_NAME, 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.`);
+    }
+
+    let exclude = settings?.exclude || [];
+
+    // Exclude shown photo dome or environment helper from bounding box calculation
+    const photoDome = this.scene.getNodeByName(backgroundDomeName) as undefined | PhotoDome;
+    const photoDomeMeshes = photoDome?.getChildMeshes();
+    if (photoDomeMeshes?.length) {
+      exclude = [...exclude, ...photoDomeMeshes];
+    }
+
+    const envHelper = this.scene.metadata?.[envHelperMetadataName] as undefined | EnvironmentHelper;
+    if (envHelper?.rootMesh) {
+      exclude = [...exclude, envHelper.rootMesh];
+    }
+
+    // get bounding box of all visible meshes, this is the base for the autofocus algorithm
+    const boundingBox = await this.calculateBoundingBox(exclude);
+
+    const radius = boundingBox.getBoundingInfo().boundingSphere.radius;
+    const center = boundingBox.getBoundingInfo().boundingSphere.center;
+    const diameter = radius * 2;
+
+    // set lower radius limit on edge of bounding sphere to make sure that we can't dive into the meshes
+    activeCamera.lowerRadiusLimit = radius;
+
+    // additional settings
+    // constants for division are taken directly from Babylon.js repository
+    activeCamera.minZ = Math.min(radius / Viewer._autofocusConstants.minZ, 1);
+    if (settings?.adjustWheelPrecision !== false) {
+      activeCamera.wheelPrecision = Viewer._autofocusConstants.wheelPrecision / radius;
+    }
+    if (settings?.adjustPanningSensibility !== false) {
+      activeCamera.panningSensibility = Viewer._autofocusConstants.panningSensibility / diameter;
+    }
+    if (settings?.adjustPinchPrecision !== false) {
+      activeCamera.pinchPrecision = Viewer._autofocusConstants.pinchPrecision / radius;
+    }
+
+    const radiusFactor = settings?.radiusFactor ?? 1.5;
+    const alpha = (settings?.alpha ?? -90) * (Math.PI / 180);
+    const beta = (settings?.beta ?? 90) * (Math.PI / 180);
+
+    const newCameraPosition = {
+      alpha: alpha,
+      beta: beta,
+      // this calculation is a bit "simplified", as it doesn't consider the viewport ratio or the frustum angle
+      // but it's also done this way in the Babylon.js repository, so it should be fine for us
+      radius: diameter * radiusFactor,
+      target: center,
+    };
+
+    await this.animationManager.animateToPlacement(activeCamera, newCameraPosition, settings?.animation);
+  }
+
+  /**
+   * Resets everything by calling {@link destroy} to clear all references and {@link bootstrap} to setup a clean
+   * environment
+   */
+  public async reset(tagManagerParameterValues: TagManagerParameterValue[]): Promise<Viewer> {
+    await this.destroy();
+    return this.bootstrap(tagManagerParameterValues);
+  }
+
+  /**
+   * 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;
+      (plane.material as StandardMaterial).specularColor = new Color3(0, 0, 0);
+      (plane.material as StandardMaterial).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;
+  }
+
+  /**
+   * Prints defined instances from SetupJson to the console.
+   */
+  protected printInstanceDefinitions(setupJson: SetupJson) {
+    console.info(
+      'The following variant instances have been read from the given spec: ',
+      setupJson.instances.map(o => o.name)
+    );
+  }
+
+  /**
+   * @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;
+    }
+    // register observers for tag manager
+    this.tagManager.registerNewTransformNodeObservers(scene);
+    this.broadcastEvent(Event.SCENE_PROCESSING_END, scene);
+    return scene;
+  }
+
+  /**
+   * Register custom file loader for babylon files which adds "missing-material" metadata to meshes which reference
+   * materials that are not present in the `materials` section of the given babylon file.
+   *
+   * Required for babylon files & materials loaded from "Combeenation configurator assets".
+   */
+  protected initCbnBabylonLoaderPlugin() {
+    const previousLoaderPlugin = SceneLoader.GetPluginForExtension('babylon') as ISceneLoaderPlugin;
+    const customLoaderPlugin = getCustomCbnBabylonLoaderPlugin(previousLoaderPlugin);
+    SceneLoader.RegisterPlugin(customLoaderPlugin);
+  }
+
+  /**
+   * Batch creation of multiple {@link VariantInstance} objects with a {@link SetupJson} object passed
+   */
+  protected async createVariantInstances(
+    tagManagerParameterValues?: TagManagerParameterValue[]
+  ): Promise<VariantInstance[]> {
+    const setupJson = SpecStorage.get<SetupJson>('setup');
+    const instances: VariantInstance[] = [];
+    for (const instanceDefinition of setupJson.instances) {
+      if (isArray(tagManagerParameterValues)) {
+        instanceDefinition.tagManagerParameterValues = tagManagerParameterValues;
+      }
+      // don't create the instance right away if `lazy` is set, register it for later creation (on first usage) instead
+      // however if the variant should be `visible` by default, `lazy` loading doesn't make sense and should therefore
+      // be overruled by the `visible` flag
+      if (instanceDefinition.lazy && instanceDefinition.parameters?.visible !== true) {
+        this.variantInstances.register(instanceDefinition);
+        continue;
+      }
+      const instance = await this.variantInstances.create(
+        instanceDefinition.variant,
+        instanceDefinition.name,
+        instanceDefinition.parameters,
+        instanceDefinition.tagManagerParameterValues
+      );
+      instances.push(instance);
+    }
+    return instances;
+  }
+}