@combeenation/3d-viewer 6.0.0 → 6.1.0-beta2

package/src/api/classes/viewer.ts

@@ -1,670 +1,672 @@
-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 { backgroundDomeName, envHelperMetadataName } from '../util/babylonHelper';
-import { debounce, loadJavascript, loadJson } from '../util/resourceHelper';
-import { getCustomCbnBabylonLoaderPlugin } from '../util/sceneLoaderHelper';
-import { isMeshIncludedInExclusionList } from '../util/structureHelper';
-import { AnimationInterface } from './animationInterface';
-import { Event } from './event';
-import { EventBroadcaster } from './eventBroadcaster';
-import { Parameter } from './parameter';
-import { Variant } from './variant';
-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 { 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 {
-  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;
-
-  protected _inspectorLoaded: 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);
-
-    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
-    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 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 BabylonJS 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 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.`);
-    }
-
-    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);
-
-    // 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;
-      (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;
-    }
-    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(): Promise<VariantInstance[]> {
-    const setupJson = SpecStorage.get<SetupJson>('setup');
-    const instances: VariantInstance[] = [];
-    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);
-  }
-}
+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 { 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 { isMeshIncludedInExclusionList } from '../util/structureHelper';
+import { AnimationInterface } from './animationInterface';
+import { Event } from './event';
+import { EventBroadcaster } from './eventBroadcaster';
+import { Parameter } from './parameter';
+import { Variant } from './variant';
+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 { 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 {
+  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;
+
+  protected _inspectorLoaded: boolean = false;
+
+  static version = buildInfo.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);
+
+    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
+    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 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 BabylonJS 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 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.`);
+    }
+
+    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);
+
+    // 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;
+      (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;
+    }
+    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(): Promise<VariantInstance[]> {
+    const setupJson = SpecStorage.get<SetupJson>('setup');
+    const instances: VariantInstance[] = [];
+    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);
+  }
+}