@combeenation/3d-viewer 0.0.1

package/src/api/classes/viewer.ts

@@ -0,0 +1,742 @@
+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 { 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 _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](./../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();
+    }
+    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();
+    // set tag manager values
+    if (tagManagerParameterValues) {
+      await this.tagManager.setParameterValues(tagManagerParameterValues);
+    }
+    // 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 (!window.BABYLON?.Inspector) {
+      // 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.27.1/babylon.min.js');
+
+      DebugLayer.InspectorURL =
+        'https://cdn.jsdelivr.net/npm/babylonjs-inspector@5.27.1/babylon.inspector.bundle.max.min.js';
+    }
+
+    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);
+
+    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(): Promise<VariantInstance[]> {
+    const setupJson = SpecStorage.get<SetupJson>('setup');
+    const instances: VariantInstance[] = [];
+    for (const instanceDefinition of setupJson.instances) {
+      // 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;
+      }
+      instances.push(
+        await this.variantInstances.create(
+          instanceDefinition.variant,
+          instanceDefinition.name,
+          instanceDefinition.parameters
+        )
+      );
+    }
+    return instances;
+  }
+}