@combeenation/3d-viewer 6.5.0 → 7.0.0-beta2

package/src/api/classes/variant.ts

@@ -1,884 +1,933 @@
-import { deactivateTransformNode, getDottedPathForNode, injectNodeMetadata } from '../util/babylonHelper';
-import { loadJson, mergeMaps } from '../util/resourceHelper';
-import { DottedPath } from './dottedPath';
-import { Element } from './element';
-import { Event } from './event';
-import { Parameter } from './parameter';
-import { ParameterObservable } from './parameterObservable';
-import { Parameterizable } from './parameterizable';
-import { VariantParameterizable } from './variantParameterizable';
-import { Viewer } from './viewer';
-import { ViewerLight } from './viewerLight';
-import { Light } from '@babylonjs/core/Lights/light';
-import '@babylonjs/core/Loading/Plugins/babylonFileLoader';
-import { SceneLoader } from '@babylonjs/core/Loading/sceneLoader';
-import { Material } from '@babylonjs/core/Materials/material';
-import { Mesh } from '@babylonjs/core/Meshes/mesh';
-import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
-import { AssetContainer } from '@babylonjs/core/assetContainer';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_clearcoat';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_ior';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_pbrSpecularGlossiness';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_sheen';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_specular';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_translucency';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_transmission';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_unlit';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_variants';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_texture_basisu';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_texture_transform';
-import '@babylonjs/loaders/glTF/2.0/glTFLoader';
-import { cloneDeep, concat, get, isEmpty, isEqual, isString, merge, set } from 'lodash-es';
-
-/**
- * A concrete "Variant". Most of these are handled by either the {@link Viewer} or {@link VariantInstance}.
- */
-export class Variant extends Parameterizable {
-  public assetContainer: AssetContainer;
-
-  public readonly elements: Element[] = [];
-
-  public readonly viewerLights: ViewerLight[] = [];
-
-  public structureJson: StructureJson;
-
-  protected _dottedNodes: Map<DottedPath, TransformNode> | undefined;
-
-  protected readonly _children: Map<string, Variant> = new Map();
-
-  protected readonly _parameterObservers: Map<string, ParameterObserver[]> = new Map();
-
-  /**
-   * @internal
-   */
-  private parametersInitialized: boolean = false;
-
-  /**
-   * Constructor.
-   */
-  protected constructor(
-    public readonly name: string,
-    protected readonly _structureJson: StructureJson,
-    public readonly viewer: Viewer,
-    public readonly parent?: Variant
-  ) {
-    super(cloneDeep(_structureJson.parameterDeclaration), cloneDeep(_structureJson.parameters));
-    for (const parameter in _structureJson.parameterDeclaration) {
-      if (!(parameter in (_structureJson.parameters || []))) {
-        throw new Error(`No default value for parameter "${parameter}" defined.`);
-      }
-    }
-    this.assetContainer = new AssetContainer(viewer.scene);
-    this.structureJson = cloneDeep(_structureJson);
-  }
-
-  /**
-   * Creates a {@link Variant} based on given parameters.
-   *
-   * @throws Error if "gltf" property is provided without a filename
-   */
-  public static async create(
-    name: string,
-    structureJson: StructureJson,
-    viewer: Viewer,
-    parent?: Variant
-  ): Promise<Variant> {
-    const variant = new Variant(name, structureJson, viewer, parent);
-    await variant.loadAssets();
-    return variant;
-  }
-
-  /**
-   * The ancestor {@link Variant}s ordered from top to bottom in the built tree.
-   */
-  get ancestors(): Variant[] {
-    const ancestors = [];
-    let variant: Variant = this;
-    while (variant.parent) {
-      ancestors.unshift(variant.parent);
-      variant = variant.parent;
-    }
-    return ancestors;
-  }
-
-  /**
-   * The root {@link Variant}.
-   */
-  get root(): Variant {
-    return this.ancestors[0] ?? this;
-  }
-
-  /**
-   * The {@link DottedPath} in the built tree of {@link Variant}s.
-   * E.g. "_.top-1.sub-2.sub-sub-3"
-   */
-  get dottedPath(): DottedPath {
-    const parentIds = this.ancestors.map(ancestor => {
-      return ancestor.name;
-    });
-    return DottedPath.createFromParts(parentIds).addPart(this.name);
-  }
-
-  /**
-   * The id representing a {@link DottedPath}.
-   */
-  get id(): string {
-    const dottedPath = DottedPath.create(this.dottedPath);
-    dottedPath.shiftPart(); // remove root
-    return dottedPath.path || '_';
-  }
-
-  /**
-   * The defined glTF Asset.
-   */
-  get glTF(): Asset | undefined {
-    if (this.structureJson.glTF) {
-      if (isString(this.structureJson.glTF)) {
-        return {
-          rootUrl: this.structureJson.glTF,
-          fileName: undefined,
-        };
-      }
-      if (isEmpty(this.structureJson.glTF.rootUrl)) {
-        throw new Error(`No "rootUrl" defined in "glTF" definition for variant "${this.id}".`);
-      }
-      return this.structureJson.glTF;
-    }
-  }
-
-  /**
-   * The defined glTF URI.
-   */
-  get glTFUri(): string | undefined {
-    if (this.glTF) {
-      return [this.glTF.rootUrl, this.glTF.fileName].join('');
-    }
-  }
-
-  /**
-   * The inherited defined glTF URI.
-   */
-  get inheritedGlTFUri(): string | undefined {
-    if (!this.glTFUri && this.parent) {
-      return this.parent.inheritedGlTFUri;
-    }
-    return this.glTFUri;
-  }
-
-  /**
-   * The TransformNodes of the {@link Variant}.
-   */
-  get nodes(): TransformNode[] {
-    const rootNodes = this.assetContainer
-      .getNodes()
-      .filter(n => n instanceof TransformNode && !n.parent) as TransformNode[];
-    return rootNodes;
-  }
-
-  /**
-   * The {@link ViewerLight}s of the {@link Variant}.
-   */
-  get lights(): Light[] {
-    return this.assetContainer.lights;
-  }
-
-  /**
-   * All TransformNodes of the {@link Variant} mapped flat with a {@link DottedPath}.
-   */
-  get dottedNodes(): Map<DottedPath, TransformNode> {
-    if (!this._dottedNodes) {
-      const nodes = this.assetContainer.getNodes().filter(n => n instanceof TransformNode);
-      const dottedNodes = new Map();
-      nodes.forEach(node => {
-        dottedNodes.set(node.metadata.dottedPath, node);
-      });
-      this._dottedNodes = dottedNodes;
-    }
-    return this._dottedNodes;
-  }
-
-  /**
-   * The Materials of the {@link Variant}.
-   */
-  get materials(): Material[] {
-    return this.assetContainer.materials;
-  }
-
-  /**
-   * All {@link Element}s from this {@link Variant}'s parents.
-   */
-  get inheritedElements(): Element[] {
-    let elements: Element[] = [];
-    this.ancestors.forEach(ancestor => {
-      elements = concat(elements, ancestor.elements);
-    });
-    return concat(elements, this.elements);
-  }
-
-  /**
-   * All {@link ViewerLight}s inherited from this {@link Variant}'s parents.
-   */
-  get inheritedViewerLights(): ViewerLight[] {
-    let viewerLights: ViewerLight[] = [];
-    this.ancestors.forEach(ancestor => {
-      viewerLights = concat(viewerLights, ancestor.viewerLights);
-    });
-    return concat(viewerLights, this.viewerLights);
-  }
-
-  /**
-   * All TransformNodes inherited from this {@link Variant}'s parents.
-   */
-  get inheritedNodes(): TransformNode[] {
-    let nodes: TransformNode[] = [];
-    this.ancestors.forEach(ancestor => {
-      nodes = concat(nodes, ancestor.nodes);
-    });
-    return concat(nodes, this.nodes);
-  }
-
-  /**
-   * All TransformNodes inherited from this {@link Variant}'s parents mapped flat with a {@link DottedPath}.
-   */
-  get inheritedDottedNodes(): Map<DottedPath, TransformNode> {
-    let dottedNodes = this.dottedNodes;
-    this.ancestors.forEach(ancestor => {
-      dottedNodes = mergeMaps(dottedNodes, ancestor.dottedNodes);
-    });
-    return dottedNodes;
-  }
-
-  /**
-   * All Lights inherited from this {@link Variant}'s parents.
-   */
-  get inheritedLights(): Light[] {
-    let lights: Light[] = [];
-    this.ancestors.forEach(ancestor => {
-      lights = concat(lights, ancestor.lights);
-    });
-    return concat(lights, this.lights);
-  }
-
-  /**
-   * The {@link ParameterDeclarations} inherited from this {@link Variant}'s parents.
-   */
-  get inheritedParameterDeclaration(): ParameterDeclarations {
-    const declaration = {};
-    this.ancestors.forEach(ancestor => {
-      merge(declaration, ancestor.parameterDeclaration);
-    });
-    return merge(declaration, this.parameterDeclaration);
-  }
-
-  /**
-   * The {@link ParameterBag} inherited from this {@link Variant}'s parents.
-   */
-  get inheritedParameters(): ParameterBag {
-    const parameters = {};
-    this.ancestors.forEach(ancestor => {
-      merge(parameters, ancestor.parameters);
-    });
-    return merge(parameters, this.parameters);
-  }
-
-  /**
-   * All Materials from this {@link Variant}'s parents.
-   */
-  get inheritedMaterials(): Material[] {
-    let materials: Material[] = [];
-    this.ancestors.forEach(ancestor => {
-      materials = concat(materials, ancestor.materials);
-    });
-    return concat(materials, this.materials);
-  }
-
-  /**
-   * Gets the direct children of the current {@link Variant}.
-   */
-  public async getChildren(): Promise<Variant[]> {
-    const children: Variant[] = [];
-    for (const name in this.structureJson.variants) {
-      children.push(await this.getDescendant(name));
-    }
-    return children;
-  }
-
-  /**
-   *  Gets a descendant {@link Variant} of the current {@link Variant} relative to its {@link DottedPath}.
-   *  If you have the dotted path `_.product_x.variant_blue.with_yellow_highlight` in a tree and you operate on the
-   *  `product_x`, you can call `this.getDescendant('variant_blue.with_yellow_highlight')` to get the lowermost
-   *  {@link Variant}.
-   */
-  public async getDescendant(dottedPath: DottedPathArgument): Promise<Variant> {
-    const _dottedPath = DottedPath.create(dottedPath);
-    const [name, ...descendantParts] = _dottedPath.parts;
-    let variant;
-    if (this._children.has(name)) {
-      variant = this._children.get(name);
-    } else {
-      if (!this.structureJson.variants) {
-        throw new Error(`Missing key "variants" in JSON structure for variant "${this.id}".`);
-      }
-      if (!this.structureJson.variants[name]) {
-        throw new Error(`Variant "${_dottedPath.path}" not defined in JSON structure for variant "${this.id}".`);
-      }
-      if (this.structureJson.variants[name].file) {
-        const file = this.structureJson.variants[name].file as string;
-        variant = await Variant.create(name, await loadJson<StructureJson>(file), this.viewer, this);
-      } else {
-        variant = await Variant.create(name, this.structureJson.variants[name], this.viewer, this);
-      }
-      this._children.set(name, variant);
-    }
-    if (!variant) {
-      throw new Error(`Variant "${_dottedPath.path}" was not created.`);
-    }
-    if (descendantParts.length > 0) {
-      return await variant.getDescendant(DottedPath.createFromParts(descendantParts));
-    }
-    return variant;
-  }
-
-  /**
-   * Gets the desired {@link Element} of the current {@link Variant} relative to its {@link DottedPath}.
-   * Uses the mechanism of {@link getDescendant} to resolve the appropriate variant in tree.
-   */
-  public async getElement(dottedPath: DottedPathArgument): Promise<Element> {
-    const _dottedPath = DottedPath.create(dottedPath);
-    const elementName = _dottedPath.popPart();
-    let variant: Variant = this;
-    if (_dottedPath.parts.length > 0) {
-      variant = await this.getDescendant(_dottedPath);
-    }
-    if (variant.inheritedElements.length === 0) {
-      throw new Error(
-        `No elements for variant "${variant.id}" found. ` +
-          `Either none are defined or they are not initialized (are you operating on the appropriate living?).`
-      );
-    }
-    let element;
-    variant.inheritedElements.forEach(_element => {
-      if (_element.name === elementName) {
-        element = _element;
-      }
-    });
-    if (!element) {
-      throw new Error(`Element with name "${elementName}" does not exist for variant "${variant.id}".`);
-    }
-    return element;
-  }
-
-  /**
-   * Gets the desired {@link ViewerLight} of the current {@link Variant} relative to its {@link DottedPath}.
-   * Uses the mechanism of {@link getDescendant} to resolve the appropriate variant in tree.
-   */
-  public async getViewerLight(dottedPath: DottedPathArgument): Promise<ViewerLight> {
-    const _dottedPath = DottedPath.create(dottedPath);
-    const viewerLightName = _dottedPath.popPart();
-    let variant: Variant = this;
-    if (_dottedPath.parts.length > 0) {
-      variant = await this.getDescendant(_dottedPath);
-    }
-    if (variant.inheritedViewerLights.length === 0) {
-      throw new Error(
-        `No viewerLights for variant "${variant.id}" found. ` +
-          `Either none are defined or they are not initialized (are you operating on the appropriate living?).`
-      );
-    }
-    let viewerLight;
-    variant.inheritedViewerLights.forEach(_viewerLight => {
-      if (_viewerLight.name === viewerLightName) {
-        viewerLight = _viewerLight;
-      }
-    });
-    if (!viewerLight) {
-      throw new Error(`ViewerLight with name "${viewerLightName}" does not exist for variant "${variant.id}".`);
-    }
-    return viewerLight;
-  }
-
-  /**
-   * A proxy for directly getting a Node from an {@link Element} by its {@link DottedPath}s.
-   */
-  public async getNode(
-    elementDottedPath: DottedPathArgument,
-    nodeDottedPath: DottedPathArgument
-  ): Promise<TransformNode> {
-    const element = await this.getElement(elementDottedPath);
-    return element.getNode(nodeDottedPath);
-  }
-
-  /**
-   * A proxy for directly getting a Mesh from an {@link Element} by its {@link DottedPath}s.
-   */
-  public async getMesh(
-    elementDottedPath: DottedPathArgument,
-    meshDottedPath: DottedPathArgument
-  ): Promise<Mesh | null> {
-    const element = await this.getElement(elementDottedPath);
-    return element.getMesh(meshDottedPath);
-  }
-
-  /**
-   * Creates a living clone of this {@link Variant}. Will clone all parent {@link Variant}s in tree.
-   *
-   * @emit {@link Event.VARIANT_CREATED}
-   * @ignore
-   */
-  public async createLiving(parameters?: ParameterBag): Promise<Variant> {
-    const parent = await this.parent?.createLiving();
-    const variant = new Variant(this.name, this._structureJson, this.viewer, parent);
-    parent?._children.set(variant.name, variant);
-    variant.assetContainer = this.assetContainer;
-    variant.parameterObservers = cloneDeep(this.parameterObservers);
-    await variant.createElements();
-    await variant.createViewerLights();
-    variant.addParameterObservers();
-    await variant.bootstrapParameters(parameters);
-    this.broadcastEvent(Event.VARIANT_CREATED, variant);
-    return variant;
-  }
-
-  /**
-   * Destroys this {@link Variant}, all parents and destroy the {@link Element}s.
-   */
-  public destroy(): Variant {
-    this.elements.forEach(element => element.destroy());
-    if (this.parent) {
-      this.parent.destroy();
-    }
-    this.broadcastEvent(Event.VARIANT_DESTROYED, this);
-    return this;
-  }
-
-  /**
-   * Places the given {@link ParameterBag} in the {@link Variant}'s parameters, replaces all patterns in the
-   * {@link StructureJson}, broadcasts all {@link ParameterObserver}s and delegates them to its {@link Element}s.
-   *
-   * @emit {@link Event.VARIANT_PARAMETER_COMMITTED}
-   */
-  public async commitParameters(parameters?: ParameterBag): Promise<Variant> {
-    parameters = merge({}, parameters);
-
-    // remember old parameter values for later comparison
-    const oldParameters = cloneDeep(this.inheritedParameters);
-
-    // replace patterns in given parameters
-    let _parameters = JSON.stringify(parameters);
-    for (const parameter in this.inheritedParameters) {
-      const value = this.inheritedParameters[parameter];
-      const search = new RegExp(`\\$\\{${parameter}\\}`, 'g');
-      _parameters = _parameters.replace(search, value.toString());
-    }
-    merge(parameters, JSON.parse(_parameters));
-
-    // merge inherited parameters and replaced given parameters
-    const mergedParameters = merge({}, this.inheritedParameters, parameters);
-
-    // replace patterns in structure parameters
-    const structureParameters = this._structureJson.parameters || {};
-    let _structureParameters = JSON.stringify(structureParameters);
-    for (const parameter in mergedParameters) {
-      const value = mergedParameters[parameter];
-      const search = new RegExp(`\\$\\{${parameter}\\}`, 'g');
-      _structureParameters = _structureParameters.replace(search, value.toString());
-    }
-    const replacedStructureParameters = JSON.parse(_structureParameters);
-
-    // calculate which replaced structure parameters have changed and should overload given parameters
-    const differentStructureParameters: ParameterBag = {};
-    for (const parameter in replacedStructureParameters) {
-      if (!isEqual(structureParameters[parameter], replacedStructureParameters[parameter])) {
-        differentStructureParameters[parameter] = replacedStructureParameters[parameter];
-      }
-    }
-
-    // merge replaced structure parameters and given inherited parameters to structure parameters
-    merge(this.parameters, mergedParameters, differentStructureParameters);
-
-    // inherited parameters are now the new parameters to process
-    const newParameters = this.inheritedParameters;
-
-    // replace all parameter patterns in structure json
-    let structure = JSON.stringify(this._structureJson);
-    for (const parameter in newParameters) {
-      const value = newParameters[parameter];
-      const search = new RegExp(`\\$\\{${parameter}\\}`, 'g');
-      structure = structure.replace(search, value.toString());
-    }
-    this.structureJson = JSON.parse(structure);
-
-    // handle parameter observers
-    let observerPromises: Promise<void | ParameterObserver>[] = [];
-    for (const parameter in newParameters) {
-      const oldParameterValue = oldParameters[parameter];
-      const newParameterValue = newParameters[parameter];
-      this.assertParameter(this.inheritedParameterDeclaration, parameter, newParameterValue);
-      if (oldParameterValue === newParameterValue && this.parametersInitialized) {
-        continue;
-      }
-      // parameter changed
-      const parameterObservers = mergeMaps(this._parameterObservers, this.parameterObservers);
-      if (parameterObservers.has(parameter)) {
-        const observers = parameterObservers.get(parameter)!;
-        observerPromises = concat(
-          observerPromises,
-          observers.map(observer => {
-            const observerResult = observer(this, oldParameterValue, newParameterValue);
-            return Promise.resolve(observerResult).then(() => {
-              if (this.parametersInitialized) {
-                this.broadcastEvent(
-                  Event.VARIANT_PARAMETER_COMMITTED,
-                  this,
-                  parameter,
-                  oldParameterValue,
-                  newParameterValue
-                );
-              }
-            });
-          })
-        );
-      }
-    }
-    await Promise.all(observerPromises);
-
-    // broadcast that bag has been committed
-    this.broadcastEvent(Event.VARIANT_PARAMETER_BAG_COMMITTED, this, oldParameters, newParameters);
-
-    // commit parameters to elements
-    await this.commitParametersToElements(newParameters);
-
-    // commit parameters to lights
-    await this.commitParametersToViewerLights(newParameters);
-
-    // propagate parameters to parent
-    if (this.parent) {
-      await this.parent.commitParameters(this.parameters);
-    }
-
-    return this;
-  }
-
-  /**
-   * Adds an observer function for camera matrix changes for given `dottedPath` representing the {@link Element}
-   * and the `traceable`. The `observer` gets 2 parameters: the `AbstractMesh` and a `ClientRect` object.
-   */
-  public async addTraceableObserver(
-    dottedPath: DottedPathArgument,
-    observer: CallableFunction,
-    payload?: any
-  ): Promise<Element> {
-    const _dottedPath = DottedPath.create(dottedPath);
-    const traceableName = _dottedPath.popPart();
-    if (!traceableName) {
-      throw new Error(
-        `The dottedPath must consist of the element and the name of the defined corresponding ` +
-          `traceable ("${_dottedPath.path}" given).`
-      );
-    }
-    const element = await this.getElement(_dottedPath);
-    return element.addTraceableObserver(traceableName, observer, payload);
-  }
-
-  /**
-   * Loads {@link glTFUri} with assets, adds them to the {@link Variant}'s `assetContainer` and deactivates the meshes.
-   * (for further processing).
-   * @emits {@link Event.ASSET_LOADING_START}
-   * @emits {@link Event.ASSET_LOADING_END}
-   */
-  protected async loadAssets(): Promise<Variant> {
-    this.broadcastEvent(Event.ASSET_LOADING_START, this);
-
-    const promisifiedLoader = new Promise<Variant>((resolve, reject) => {
-      if (!this.structureJson) {
-        this.broadcastEvent(Event.ASSET_LOADING_END, this);
-        return resolve(this);
-      }
-      if (!this.glTF) {
-        this.broadcastEvent(Event.ASSET_LOADING_END, this);
-        return resolve(this);
-      }
-      SceneLoader.LoadAssetContainer(
-        this.glTF.rootUrl,
-        this.glTF.fileName,
-        this.viewer.scene,
-        // on success
-        container => {
-          this.assetContainer = container;
-          const nodes = this.assetContainer.getNodes().filter(n => n instanceof TransformNode) as TransformNode[];
-          nodes.forEach(node => {
-            deactivateTransformNode(node, false);
-            injectNodeMetadata(node, { dottedPath: getDottedPathForNode(node) }, false);
-          });
-          this.assetContainer.lights.forEach(light => {
-            light.setEnabled(false);
-            injectNodeMetadata(light, { dottedPath: getDottedPathForNode(light) }, false);
-            this.viewer.scene.addLight(light);
-          });
-          this.assetContainer.cameras.forEach(camera => {
-            camera.setEnabled(false);
-            injectNodeMetadata(camera, { dottedPath: getDottedPathForNode(camera) }, false);
-            this.viewer.scene.addCamera(camera);
-          });
-          this.assetContainer.materials.forEach(material => this.viewer.scene.materials.push(material));
-          this.broadcastEvent(Event.ASSET_LOADING_END, this);
-          resolve(this);
-        },
-        // on progress
-        undefined,
-        // on error
-        reason => {
-          this.broadcastEvent(Event.ASSET_LOADING_END, this);
-          throw new Error(`Error loading assets for variant "${this.id}": ${reason}.`);
-        }
-      );
-    });
-    return await promisifiedLoader;
-  }
-
-  /**
-   * Commits given parameters to all {@link Element}s.
-   */
-  protected async commitParametersToElements(parameters: ParameterBag) {
-    await Promise.all(
-      this.elements.map(element => this.commitParametersToVariantParameterizable(parameters, element, 'elements'))
-    );
-  }
-
-  /**
-   * Commits given parameters to all {@link ViewerLight}s.
-   */
-  protected async commitParametersToViewerLights(parameters: ParameterBag) {
-    await Promise.all(
-      this.viewerLights.map(viewerLight =>
-        this.commitParametersToVariantParameterizable(parameters, viewerLight, 'lights')
-      )
-    );
-  }
-
-  /**
-   * Commits given parameters to a {@link VariantParameterizable} and updates the according definition with given
-   * key in the {@link StructureJson}. The `definitionKey` "elements" for example will update the definition in
-   * `this.structureJson.elements`.
-   */
-  protected async commitParametersToVariantParameterizable(
-    parameters: ParameterBag,
-    parameterizable: VariantParameterizable,
-    definitionKey: string
-  ): Promise<ParameterObservable> {
-    const initialDefinition = get(this._structureJson, definitionKey)[parameterizable.name];
-    let initialDefinitionStr = JSON.stringify(initialDefinition);
-    const _parameters: ParameterBag = {};
-    for (const parameter in parameters) {
-      const dpp = DottedPath.create(parameter);
-      if (dpp.shiftPart() !== parameterizable.name) {
-        continue;
-      }
-      // we got a parameterizable ("element") parameter
-      let parameterValue = parameters[parameter];
-      const parameterizableParameter = dpp.path;
-      // If the variant is explicitly hidden, we must not override the visibility with element parameters. We need
-      // an exception for visibility to avoid overloading already applied element parameters with element parameters
-      // defined in the variant spec ("dotted parameters").
-      // @see https://github.com/Combeenation/3d-viewer/issues/44
-      if (parameterizableParameter === Parameter.VISIBLE && parameters[Parameter.VISIBLE] === false) {
-        parameterValue = false;
-      }
-      _parameters[parameterizableParameter] = parameterValue;
-      const search = new RegExp(`\\$\\{${parameterizableParameter}\\}`, 'g');
-      initialDefinitionStr = initialDefinitionStr.replace(search, parameterValue.toString());
-    }
-    const definition = get(this.structureJson, definitionKey);
-    definition[this.name] = JSON.parse(initialDefinitionStr);
-    set(this.structureJson, definitionKey, definition);
-    return await parameterizable.commitParameters(_parameters);
-  }
-
-  /**
-   * Commits given {@link Parameter} to the {@link Variant}'s {@link Element}s.
-   */
-  protected async commitParameterToElements(parameter: string, value: ParameterValue): Promise<Variant> {
-    const promises = [];
-    for (const element of this.elements) {
-      const paramShowsVariant = Parameter.VISIBLE === parameter && value;
-
-      // Fixes https://combeenation.youtrack.cloud/issue/CB-7773
-      // Don't enable/show the variants element if it is explicitly hidden via its element parameters.
-      // E.g. via spec:
-      // ```
-      // variants: {
-      //   theVariant: {
-      //     elements: {
-      //       Main: ['root.main'],
-      //       Secondary: ['root.secondary'],
-      //     },
-      //     parameters: {
-      //       // !!! The element `Secondary` should **not** be enabled when its containing variant is enabled !!!
-      //       'Secondary.visible': false,
-      //     }
-      //   }
-      // }
-      // ```
-      const elVisibleParamPath = DottedPath.create([element.name, Parameter.VISIBLE]).toString();
-      const elVisibleParamValue = this.inheritedParameters[elVisibleParamPath];
-      const elVisibleParamValueParsed = elVisibleParamValue && Parameter.parseBoolean(elVisibleParamValue);
-      const elIsHiddenViaParams = elVisibleParamValueParsed === false;
-      if (paramShowsVariant && elIsHiddenViaParams) continue;
-
-      // Fixes https://combeenation.youtrack.cloud/issue/CB-7809
-      // Apply element material before showing the element to prevent loading of the elements "original" material which
-      // is never shown when "overwritten" by elements material param.
-      const elMaterialParamPath = DottedPath.create([element.name, Parameter.MATERIAL]).toString();
-      const elMaterialParamValue = this.inheritedParameters[elMaterialParamPath];
-      if (paramShowsVariant && elMaterialParamValue) {
-        await element.commitParameter(Parameter.MATERIAL, elMaterialParamValue);
-      }
-
-      promises.push(element.commitParameter(parameter, value));
-    }
-    await Promise.all(promises);
-    return this;
-  }
-
-  /**
-   * Commits given {@link Parameter} to the {@link Variant}'s {@link Element}s.
-   */
-  protected async commitParameterToViewerLights(parameter: string, value: ParameterValue): Promise<Variant> {
-    const promises = [];
-    for (const viewerLight of this.viewerLights) {
-      promises.push(viewerLight.commitParameter(parameter, value));
-    }
-    await Promise.all(promises);
-    return this;
-  }
-
-  /**
-   * Adds the default {@link ParameterObserver}s which are called every time {@link commitParameters} is called.
-   */
-  protected addParameterObservers(): Variant {
-    this._parameterObservers.set(Parameter.VISIBLE, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
-        await variant.commitParameterToElements(Parameter.VISIBLE, newValue);
-        await variant.commitParameterToViewerLights(Parameter.VISIBLE, newValue);
-      },
-    ]);
-    this._parameterObservers.set(Parameter.SCALING, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
-        await variant.commitParameterToElements(Parameter.SCALING, newValue);
-        await variant.commitParameterToViewerLights(Parameter.SCALING, newValue);
-      },
-    ]);
-    this._parameterObservers.set(Parameter.MATERIAL, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
-        await variant.commitParameterToElements(Parameter.MATERIAL, newValue);
-      },
-    ]);
-    this._parameterObservers.set(Parameter.MATERIAL_COLOR, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
-        await variant.commitParameterToElements(Parameter.MATERIAL_COLOR, newValue);
-      },
-    ]);
-    this._parameterObservers.set(Parameter.MATERIAL_METALLNESS, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
-        await variant.commitParameterToElements(Parameter.MATERIAL_METALLNESS, newValue);
-      },
-    ]);
-    this._parameterObservers.set(Parameter.MATERIAL_ROUGHNESS, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
-        await variant.commitParameterToElements(Parameter.MATERIAL_ROUGHNESS, newValue);
-      },
-    ]);
-    this._parameterObservers.set(Parameter.HIGHLIGHT_COLOR, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
-        await variant.commitParameterToElements(Parameter.HIGHLIGHT_COLOR, newValue);
-      },
-    ]);
-    this._parameterObservers.set(Parameter.HIGHLIGHTED, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
-        await variant.commitParameterToElements(Parameter.HIGHLIGHTED, newValue);
-      },
-    ]);
-    this._parameterObservers.set(Parameter.POSITION, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
-        await variant.commitParameterToElements(Parameter.POSITION, newValue);
-        await variant.commitParameterToViewerLights(Parameter.POSITION, newValue);
-      },
-    ]);
-    this._parameterObservers.set(Parameter.ROTATION, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
-        await variant.commitParameterToElements(Parameter.ROTATION, newValue);
-        await variant.commitParameterToViewerLights(Parameter.ROTATION, newValue);
-      },
-    ]);
-    this._parameterObservers.set(Parameter.CAST_SHADOW, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
-        await variant.commitParameterToElements(Parameter.CAST_SHADOW, newValue);
-      },
-    ]);
-    this._parameterObservers.set(Parameter.CAST_SHADOW_FROM_LIGHTS, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
-        await variant.commitParameterToElements(Parameter.CAST_SHADOW_FROM_LIGHTS, newValue);
-      },
-    ]);
-    this._parameterObservers.set(Parameter.RECEIVE_SHADOWS, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
-        await variant.commitParameterToElements(Parameter.RECEIVE_SHADOWS, newValue);
-      },
-    ]);
-    return this;
-  }
-
-  /**
-   * Creates {@link Element}s and clones nodes into them.
-   */
-  protected async createElements(): Promise<Variant> {
-    this.createElementDefinitionsIfNotExist();
-    for (const name in this.structureJson.elements || {}) {
-      this.elements.push(await Element.create(this, name));
-    }
-    // inject node meta to all inherited elements
-    // we do this to inject the deepest and most concrete variant information to all cloned nodes in the tree
-    this.inheritedElements.forEach(element => {
-      element.nodes.forEach(node => {
-        injectNodeMetadata(node, { variant: this, variantParameterizable: element });
-      });
-    });
-    return this;
-  }
-
-  /**
-   * Creates {@link ViewerLight}s.
-   */
-  protected async createViewerLights(): Promise<Variant> {
-    for (const name in this.structureJson.lights || {}) {
-      this.viewerLights.push(await ViewerLight.create(this, name));
-    }
-    this.inheritedViewerLights.forEach(viewerLight => {
-      injectNodeMetadata(viewerLight.light, { variant: this, variantParameterizable: viewerLight });
-    });
-    return this;
-  }
-
-  /**
-   * Bootstrapping for parameters. It sets the `parametersInitialized` to true for all ancestors.
-   */
-  protected async bootstrapParameters(parameters?: ParameterBag): Promise<Variant> {
-    await this.commitParameters(merge(cloneDeep(this.parameters), parameters));
-    concat(this.ancestors, this).forEach(ancestor => (ancestor.parametersInitialized = true));
-    return this;
-  }
-
-  /**
-   * Ensures there is at least one "Main" {@link Element} for the {@link Variant} with all "root nodes" defined in path.
-   */
-  protected createElementDefinitionsIfNotExist() {
-    if (this._structureJson.elements || this.inheritedNodes.length === 0) {
-      return;
-    }
-    this._structureJson.elements = {
-      Main: { paths: { include: this.inheritedNodes.map(node => node.metadata.dottedPath.path) } },
-    };
-    this.structureJson.elements = cloneDeep(this._structureJson.elements);
-  }
-}
+import {
+  deactivateTransformNode,
+  getDottedPathForNode,
+  injectNodeMetadata,
+  intersectingNodeNames,
+  reportDuplicateNodeNames,
+} from '../util/babylonHelper';
+import { loadJson, mergeMaps } from '../util/resourceHelper';
+import { DottedPath } from './dottedPath';
+import { Element } from './element';
+import { Event } from './event';
+import { Parameter } from './parameter';
+import { ParameterObservable } from './parameterObservable';
+import { Parameterizable } from './parameterizable';
+import { VariantParameterizable } from './variantParameterizable';
+import { Viewer } from './viewer';
+import { ViewerLight } from './viewerLight';
+import { Light } from '@babylonjs/core/Lights/light';
+import '@babylonjs/core/Loading/Plugins/babylonFileLoader';
+import { SceneLoader } from '@babylonjs/core/Loading/sceneLoader';
+import { Material } from '@babylonjs/core/Materials/material';
+import { Mesh } from '@babylonjs/core/Meshes/mesh';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import { AssetContainer } from '@babylonjs/core/assetContainer';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_clearcoat';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_ior';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_pbrSpecularGlossiness';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_sheen';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_specular';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_translucency';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_transmission';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_unlit';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_variants';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_texture_basisu';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_texture_transform';
+import '@babylonjs/loaders/glTF/2.0/glTFLoader';
+import { cloneDeep, concat, get, isEmpty, isEqual, isString, merge, set } from 'lodash-es';
+
+/**
+ * A concrete "Variant". Most of these are handled by either the {@link Viewer} or {@link VariantInstance}.
+ */
+export class Variant extends Parameterizable {
+  public assetContainer: AssetContainer;
+
+  public readonly elements: Element[] = [];
+
+  public readonly viewerLights: ViewerLight[] = [];
+
+  public structureJson: StructureJson;
+
+  protected _dottedNodes: Map<DottedPath, TransformNode> | undefined;
+
+  protected readonly _children: Map<string, Variant> = new Map();
+
+  protected readonly _parameterObservers: Map<string, ParameterObserver[]> = new Map();
+
+  /**
+   * @internal
+   */
+  private parametersInitialized: boolean = false;
+
+  /**
+   * Constructor.
+   */
+  protected constructor(
+    protected readonly _variantInstance: VariantInstance | null,
+    public readonly name: string,
+    protected readonly _structureJson: StructureJson,
+    public readonly viewer: Viewer,
+    public readonly parent?: Variant
+  ) {
+    super(cloneDeep(_structureJson.parameterDeclaration), cloneDeep(_structureJson.parameters));
+    for (const parameter in _structureJson.parameterDeclaration) {
+      if (!(parameter in (_structureJson.parameters || []))) {
+        throw new Error(`No default value for parameter "${parameter}" defined.`);
+      }
+    }
+    this.assetContainer = new AssetContainer(viewer.scene);
+    this.structureJson = cloneDeep(_structureJson);
+  }
+
+  /**
+   * Creates the root {@link Variant}.
+   */
+  public static async createRoot(structureJson: StructureJson, viewer: Viewer): Promise<Variant> {
+    return Variant.create(null, '_', structureJson, viewer);
+  }
+
+  /**
+   * Creates a {@link Variant} based on given parameters.
+   *
+   * @throws Error if "gltf" property is provided without a filename
+   */
+  public static async create(
+    variantInstance: VariantInstance | null,
+    name: string,
+    structureJson: StructureJson,
+    viewer: Viewer,
+    parent?: Variant
+  ): Promise<Variant> {
+    const variant = new Variant(variantInstance, name, structureJson, viewer, parent);
+    await variant.loadAssets();
+    return variant;
+  }
+
+  /**
+   * The ancestor {@link Variant}s ordered from top to bottom in the built tree.
+   */
+  get ancestors(): Variant[] {
+    const ancestors = [];
+    let variant: Variant = this;
+    while (variant.parent) {
+      ancestors.unshift(variant.parent);
+      variant = variant.parent;
+    }
+    return ancestors;
+  }
+
+  /**
+   * The root {@link Variant}.
+   */
+  get root(): Variant {
+    return this.ancestors[0] ?? this;
+  }
+
+  /**
+   * The {@link DottedPath} in the built tree of {@link Variant}s.
+   * E.g. "_.top-1.sub-2.sub-sub-3"
+   */
+  get dottedPath(): DottedPath {
+    const parentIds = this.ancestors.map(ancestor => {
+      return ancestor.name;
+    });
+    return DottedPath.createFromParts(parentIds).addPart(this.name);
+  }
+
+  /**
+   * Gets the {@link VariantInstance} this variant was created for. There are variants without an instance (the "ghost"
+   * ones used for bootstrapping instances). The usage of {@link Variant}s without an instance is an absolute edge-case
+   * when deeply using the viewer api and working abroad best practices.
+   */
+  get variantInstance(): VariantInstance | null {
+    return this._variantInstance;
+  }
+
+  /**
+   * The id representing a {@link DottedPath}.
+   */
+  get id(): string {
+    const dottedPath = DottedPath.create(this.dottedPath);
+    dottedPath.shiftPart(); // remove root
+    return dottedPath.path || '_';
+  }
+
+  /**
+   * The defined glTF Asset.
+   */
+  get glTF(): Asset | undefined {
+    if (this.structureJson.glTF) {
+      if (isString(this.structureJson.glTF)) {
+        return {
+          rootUrl: this.structureJson.glTF,
+          fileName: undefined,
+        };
+      }
+      if (isEmpty(this.structureJson.glTF.rootUrl)) {
+        throw new Error(`No "rootUrl" defined in "glTF" definition for variant "${this.id}".`);
+      }
+      return this.structureJson.glTF;
+    }
+  }
+
+  /**
+   * The defined glTF URI.
+   */
+  get glTFUri(): string | undefined {
+    if (this.glTF) {
+      return [this.glTF.rootUrl, this.glTF.fileName].join('');
+    }
+  }
+
+  /**
+   * The inherited defined glTF URI.
+   */
+  get inheritedGlTFUri(): string | undefined {
+    if (!this.glTFUri && this.parent) {
+      return this.parent.inheritedGlTFUri;
+    }
+    return this.glTFUri;
+  }
+
+  /**
+   * The TransformNodes of the {@link Variant}.
+   */
+  get nodes(): TransformNode[] {
+    const rootNodes = this.assetContainer
+      .getNodes()
+      .filter(n => n instanceof TransformNode && !n.parent) as TransformNode[];
+    return rootNodes;
+  }
+
+  /**
+   * The {@link ViewerLight}s of the {@link Variant}.
+   */
+  get lights(): Light[] {
+    return this.assetContainer.lights;
+  }
+
+  /**
+   * All TransformNodes of the {@link Variant} mapped flat with a {@link DottedPath}.
+   */
+  get dottedNodes(): Map<DottedPath, TransformNode> {
+    if (!this._dottedNodes) {
+      const nodes = this.assetContainer.getNodes().filter(n => n instanceof TransformNode);
+      const dottedNodes = new Map();
+      nodes.forEach(node => {
+        dottedNodes.set(node.metadata.dottedPath, node);
+      });
+      this._dottedNodes = dottedNodes;
+    }
+    return this._dottedNodes;
+  }
+
+  /**
+   * The Materials of the {@link Variant}.
+   */
+  get materials(): Material[] {
+    return this.assetContainer.materials;
+  }
+
+  /**
+   * The cloned TransformNodes of all {@link Element}s created for this {@link Variant}.
+   */
+  get elementNodes(): TransformNode[] {
+    return this.elements.reduce((a, c) => a.concat(c.nodes), [] as TransformNode[]);
+  }
+
+  /**
+   * The cloned TransformNodes of all {@link Element}s created for this {@link Variant} flattened.
+   */
+  get elementNodesFlat(): TransformNode[] {
+    return this.elements.reduce((a, c) => [...a, ...c.nodesFlat], [] as TransformNode[]);
+  }
+
+  /**
+   * All {@link Element}s from this {@link Variant}'s parents.
+   */
+  get inheritedElements(): Element[] {
+    let elements: Element[] = [];
+    this.ancestors.forEach(ancestor => {
+      elements = concat(elements, ancestor.elements);
+    });
+    return concat(elements, this.elements);
+  }
+
+  /**
+   * All {@link ViewerLight}s inherited from this {@link Variant}'s parents.
+   */
+  get inheritedViewerLights(): ViewerLight[] {
+    let viewerLights: ViewerLight[] = [];
+    this.ancestors.forEach(ancestor => {
+      viewerLights = concat(viewerLights, ancestor.viewerLights);
+    });
+    return concat(viewerLights, this.viewerLights);
+  }
+
+  /**
+   * All TransformNodes inherited from this {@link Variant}'s parents.
+   */
+  get inheritedNodes(): TransformNode[] {
+    let nodes: TransformNode[] = [];
+    this.ancestors.forEach(ancestor => {
+      nodes = concat(nodes, ancestor.nodes);
+    });
+    return concat(nodes, this.nodes);
+  }
+
+  /**
+   * All TransformNodes inherited from this {@link Variant}'s parents mapped flat with a {@link DottedPath}.
+   */
+  get inheritedDottedNodes(): Map<DottedPath, TransformNode> {
+    let dottedNodes = this.dottedNodes;
+    this.ancestors.forEach(ancestor => {
+      dottedNodes = mergeMaps(dottedNodes, ancestor.dottedNodes);
+    });
+    return dottedNodes;
+  }
+
+  /**
+   * All Lights inherited from this {@link Variant}'s parents.
+   */
+  get inheritedLights(): Light[] {
+    let lights: Light[] = [];
+    this.ancestors.forEach(ancestor => {
+      lights = concat(lights, ancestor.lights);
+    });
+    return concat(lights, this.lights);
+  }
+
+  /**
+   * The {@link ParameterDeclarations} inherited from this {@link Variant}'s parents.
+   */
+  get inheritedParameterDeclaration(): ParameterDeclarations {
+    const declaration = {};
+    this.ancestors.forEach(ancestor => {
+      merge(declaration, ancestor.parameterDeclaration);
+    });
+    return merge(declaration, this.parameterDeclaration);
+  }
+
+  /**
+   * The {@link ParameterBag} inherited from this {@link Variant}'s parents.
+   */
+  get inheritedParameters(): ParameterBag {
+    const parameters = {};
+    this.ancestors.forEach(ancestor => {
+      merge(parameters, ancestor.parameters);
+    });
+    return merge(parameters, this.parameters);
+  }
+
+  /**
+   * All Materials from this {@link Variant}'s parents.
+   */
+  get inheritedMaterials(): Material[] {
+    let materials: Material[] = [];
+    this.ancestors.forEach(ancestor => {
+      materials = concat(materials, ancestor.materials);
+    });
+    return concat(materials, this.materials);
+  }
+
+  /**
+   * Gets the direct children of the current {@link Variant}.
+   */
+  public async getChildren(): Promise<Variant[]> {
+    const children: Variant[] = [];
+    for (const name in this.structureJson.variants) {
+      children.push(await this.getDescendant(name));
+    }
+    return children;
+  }
+
+  /**
+   *  Gets a descendant {@link Variant} of the current {@link Variant} relative to its {@link DottedPath}.
+   *  If you have the dotted path `_.product_x.variant_blue.with_yellow_highlight` in a tree and you operate on the
+   *  `product_x`, you can call `this.getDescendant('variant_blue.with_yellow_highlight')` to get the lowermost
+   *  {@link Variant}.
+   */
+  public async getDescendant(dottedPath: DottedPathArgument): Promise<Variant> {
+    const _dottedPath = DottedPath.create(dottedPath);
+    const [name, ...descendantParts] = _dottedPath.parts;
+    let variant;
+    if (this._children.has(name)) {
+      variant = this._children.get(name);
+    } else {
+      if (!this.structureJson.variants) {
+        throw new Error(`Missing key "variants" in JSON structure for variant "${this.id}".`);
+      }
+      if (!this.structureJson.variants[name]) {
+        throw new Error(`Variant "${_dottedPath.path}" not defined in JSON structure for variant "${this.id}".`);
+      }
+      if (this.structureJson.variants[name].file) {
+        const file = this.structureJson.variants[name].file as string;
+        variant = await Variant.create(
+          this.variantInstance,
+          name,
+          await loadJson<StructureJson>(file),
+          this.viewer,
+          this
+        );
+      } else {
+        variant = await Variant.create(
+          this.variantInstance,
+          name,
+          this.structureJson.variants[name],
+          this.viewer,
+          this
+        );
+      }
+      this._children.set(name, variant);
+    }
+    if (!variant) {
+      throw new Error(`Variant "${_dottedPath.path}" was not created.`);
+    }
+    if (descendantParts.length > 0) {
+      return await variant.getDescendant(DottedPath.createFromParts(descendantParts));
+    }
+    return variant;
+  }
+
+  /**
+   * Gets the desired {@link Element} of the current {@link Variant} relative to its {@link DottedPath}.
+   * Uses the mechanism of {@link getDescendant} to resolve the appropriate variant in tree.
+   */
+  public async getElement(dottedPath: DottedPathArgument): Promise<Element> {
+    const _dottedPath = DottedPath.create(dottedPath);
+    const elementName = _dottedPath.popPart();
+    let variant: Variant = this;
+    if (_dottedPath.parts.length > 0) {
+      variant = await this.getDescendant(_dottedPath);
+    }
+    if (variant.inheritedElements.length === 0) {
+      throw new Error(
+        `No elements for variant "${variant.id}" found. ` +
+          `Either none are defined or they are not initialized (are you operating on the appropriate living?).`
+      );
+    }
+    let element;
+    variant.inheritedElements.forEach(_element => {
+      if (_element.name === elementName) {
+        element = _element;
+      }
+    });
+    if (!element) {
+      throw new Error(`Element with name "${elementName}" does not exist for variant "${variant.id}".`);
+    }
+    return element;
+  }
+
+  /**
+   * Gets the desired {@link ViewerLight} of the current {@link Variant} relative to its {@link DottedPath}.
+   * Uses the mechanism of {@link getDescendant} to resolve the appropriate variant in tree.
+   */
+  public async getViewerLight(dottedPath: DottedPathArgument): Promise<ViewerLight> {
+    const _dottedPath = DottedPath.create(dottedPath);
+    const viewerLightName = _dottedPath.popPart();
+    let variant: Variant = this;
+    if (_dottedPath.parts.length > 0) {
+      variant = await this.getDescendant(_dottedPath);
+    }
+    if (variant.inheritedViewerLights.length === 0) {
+      throw new Error(
+        `No viewerLights for variant "${variant.id}" found. ` +
+          `Either none are defined or they are not initialized (are you operating on the appropriate living?).`
+      );
+    }
+    let viewerLight;
+    variant.inheritedViewerLights.forEach(_viewerLight => {
+      if (_viewerLight.name === viewerLightName) {
+        viewerLight = _viewerLight;
+      }
+    });
+    if (!viewerLight) {
+      throw new Error(`ViewerLight with name "${viewerLightName}" does not exist for variant "${variant.id}".`);
+    }
+    return viewerLight;
+  }
+
+  /**
+   * A proxy for directly getting a Node from an {@link Element} by its {@link DottedPath}s.
+   */
+  public async getNode(
+    elementDottedPath: DottedPathArgument,
+    nodeDottedPath: DottedPathArgument
+  ): Promise<TransformNode> {
+    const element = await this.getElement(elementDottedPath);
+    return element.getNode(nodeDottedPath);
+  }
+
+  /**
+   * A proxy for directly getting a Mesh from an {@link Element} by its {@link DottedPath}s.
+   */
+  public async getMesh(
+    elementDottedPath: DottedPathArgument,
+    meshDottedPath: DottedPathArgument
+  ): Promise<Mesh | null> {
+    const element = await this.getElement(elementDottedPath);
+    return element.getMesh(meshDottedPath);
+  }
+
+  /**
+   * Creates a living clone of this {@link Variant}. Will clone all parent {@link Variant}s in tree.
+   *
+   * @emit {@link Event.VARIANT_CREATED}
+   * @ignore
+   */
+  public async createLiving(variantInstance: VariantInstance, parameters?: ParameterBag): Promise<Variant> {
+    const parent = await this.parent?.createLiving(variantInstance);
+    const variant = new Variant(variantInstance, this.name, this._structureJson, this.viewer, parent);
+    parent?._children.set(variant.name, variant);
+    variant.assetContainer = this.assetContainer;
+    variant.parameterObservers = cloneDeep(this.parameterObservers);
+    await variant.createElements();
+    await variant.createViewerLights();
+    variant.addParameterObservers();
+    await variant.bootstrapParameters(parameters);
+    this.viewer.broadcastEvent(Event.VARIANT_CREATED, variant);
+    return variant;
+  }
+
+  /**
+   * Destroys this {@link Variant}, all parents and destroy the {@link Element}s.
+   */
+  public destroy(): Variant {
+    this.elements.forEach(element => element.destroy());
+    if (this.parent) {
+      this.parent.destroy();
+    }
+    this.broadcastEvent(Event.VARIANT_DESTROYED, this);
+    return this;
+  }
+
+  /**
+   * Places the given {@link ParameterBag} in the {@link Variant}'s parameters, replaces all patterns in the
+   * {@link StructureJson}, broadcasts all {@link ParameterObserver}s and delegates them to its {@link Element}s.
+   *
+   * @emit {@link Event.VARIANT_PARAMETER_COMMITTED}
+   */
+  public async commitParameters(parameters?: ParameterBag): Promise<Variant> {
+    parameters = merge({}, parameters);
+
+    // remember old parameter values for later comparison
+    const oldParameters = cloneDeep(this.inheritedParameters);
+
+    // replace patterns in given parameters
+    let _parameters = JSON.stringify(parameters);
+    for (const parameter in this.inheritedParameters) {
+      const value = this.inheritedParameters[parameter];
+      const search = new RegExp(`\\$\\{${parameter}\\}`, 'g');
+      _parameters = _parameters.replace(search, value.toString());
+    }
+    merge(parameters, JSON.parse(_parameters));
+
+    // merge inherited parameters and replaced given parameters
+    const mergedParameters = merge({}, this.inheritedParameters, parameters);
+
+    // replace patterns in structure parameters
+    const structureParameters = this._structureJson.parameters || {};
+    let _structureParameters = JSON.stringify(structureParameters);
+    for (const parameter in mergedParameters) {
+      const value = mergedParameters[parameter];
+      const search = new RegExp(`\\$\\{${parameter}\\}`, 'g');
+      _structureParameters = _structureParameters.replace(search, value.toString());
+    }
+    const replacedStructureParameters = JSON.parse(_structureParameters);
+
+    // calculate which replaced structure parameters have changed and should overload given parameters
+    const differentStructureParameters: ParameterBag = {};
+    for (const parameter in replacedStructureParameters) {
+      if (!isEqual(structureParameters[parameter], replacedStructureParameters[parameter])) {
+        differentStructureParameters[parameter] = replacedStructureParameters[parameter];
+      }
+    }
+
+    // merge replaced structure parameters and given inherited parameters to structure parameters
+    merge(this.parameters, mergedParameters, differentStructureParameters);
+
+    // inherited parameters are now the new parameters to process
+    const newParameters = this.inheritedParameters;
+
+    // replace all parameter patterns in structure json
+    let structure = JSON.stringify(this._structureJson);
+    for (const parameter in newParameters) {
+      const value = newParameters[parameter];
+      const search = new RegExp(`\\$\\{${parameter}\\}`, 'g');
+      structure = structure.replace(search, value.toString());
+    }
+    this.structureJson = JSON.parse(structure);
+
+    // handle parameter observers
+    let observerPromises: Promise<void | ParameterObserver>[] = [];
+    for (const parameter in newParameters) {
+      const oldParameterValue = oldParameters[parameter];
+      const newParameterValue = newParameters[parameter];
+      this.assertParameter(this.inheritedParameterDeclaration, parameter, newParameterValue);
+      if (oldParameterValue === newParameterValue && this.parametersInitialized) {
+        continue;
+      }
+      // parameter changed
+      const parameterObservers = mergeMaps(this._parameterObservers, this.parameterObservers);
+      if (parameterObservers.has(parameter)) {
+        const observers = parameterObservers.get(parameter)!;
+        observerPromises = concat(
+          observerPromises,
+          observers.map(observer => {
+            const observerResult = observer(this, oldParameterValue, newParameterValue);
+            return Promise.resolve(observerResult).then(() => {
+              if (this.parametersInitialized) {
+                this.broadcastEvent(
+                  Event.VARIANT_PARAMETER_COMMITTED,
+                  this,
+                  parameter,
+                  oldParameterValue,
+                  newParameterValue
+                );
+              }
+            });
+          })
+        );
+      }
+    }
+    await Promise.all(observerPromises);
+
+    // broadcast that bag has been committed
+    this.broadcastEvent(Event.VARIANT_PARAMETER_BAG_COMMITTED, this, oldParameters, newParameters);
+
+    // commit parameters to elements
+    await this.commitParametersToElements(newParameters);
+
+    // commit parameters to lights
+    await this.commitParametersToViewerLights(newParameters);
+
+    // propagate parameters to parent
+    if (this.parent) {
+      await this.parent.commitParameters(this.parameters);
+    }
+
+    return this;
+  }
+
+  /**
+   * Adds an observer function for camera matrix changes for given `dottedPath` representing the {@link Element}
+   * and the `traceable`. The `observer` gets 2 parameters: the `AbstractMesh` and a `ClientRect` object.
+   */
+  public async addTraceableObserver(
+    dottedPath: DottedPathArgument,
+    observer: CallableFunction,
+    payload?: any
+  ): Promise<Element> {
+    const _dottedPath = DottedPath.create(dottedPath);
+    const traceableName = _dottedPath.popPart();
+    if (!traceableName) {
+      throw new Error(
+        `The dottedPath must consist of the element and the name of the defined corresponding ` +
+          `traceable ("${_dottedPath.path}" given).`
+      );
+    }
+    const element = await this.getElement(_dottedPath);
+    return element.addTraceableObserver(traceableName, observer, payload);
+  }
+
+  /**
+   * Loads {@link glTFUri} with assets, adds them to the {@link Variant}'s `assetContainer` and deactivates the meshes.
+   * (for further processing).
+   * @emits {@link Event.ASSET_LOADING_START}
+   * @emits {@link Event.ASSET_LOADING_END}
+   */
+  protected async loadAssets(): Promise<Variant> {
+    this.broadcastEvent(Event.ASSET_LOADING_START, this);
+    return new Promise<Variant>(resolve => {
+      if (!this.structureJson) {
+        this.broadcastEvent(Event.ASSET_LOADING_END, this);
+        return resolve(this);
+      }
+      if (!this.glTF) {
+        this.broadcastEvent(Event.ASSET_LOADING_END, this);
+        return resolve(this);
+      }
+      SceneLoader.LoadAssetContainer(
+        this.glTF.rootUrl,
+        this.glTF.fileName,
+        this.viewer.scene,
+        // on success
+        container => {
+          this.assetContainer = container;
+          const nodes = this.assetContainer.getNodes().filter(n => n instanceof TransformNode) as TransformNode[];
+          reportDuplicateNodeNames(
+            intersectingNodeNames(nodes, this.viewer.scene.getNodes(), n => n instanceof TransformNode)
+          );
+          nodes.forEach(node => {
+            deactivateTransformNode(node, false);
+            injectNodeMetadata(node, { dottedPath: getDottedPathForNode(node), originalName: node.name }, false);
+          });
+          this.assetContainer.lights.forEach(light => {
+            light.setEnabled(false);
+            injectNodeMetadata(light, { dottedPath: getDottedPathForNode(light), originalName: light.name }, false);
+            this.viewer.scene.addLight(light);
+          });
+          this.assetContainer.cameras.forEach(camera => {
+            camera.setEnabled(false);
+            injectNodeMetadata(camera, { dottedPath: getDottedPathForNode(camera), originalName: camera.name }, false);
+            this.viewer.scene.addCamera(camera);
+          });
+          this.assetContainer.materials.forEach(material => this.viewer.scene.materials.push(material));
+          this.broadcastEvent(Event.ASSET_LOADING_END, this);
+          resolve(this);
+        },
+        // on progress
+        undefined,
+        // on error
+        reason => {
+          this.broadcastEvent(Event.ASSET_LOADING_END, this);
+          throw new Error(`Error loading assets for variant "${this.id}": ${reason}.`);
+        }
+      );
+    });
+  }
+
+  /**
+   * Commits given parameters to all {@link Element}s.
+   */
+  protected async commitParametersToElements(parameters: ParameterBag) {
+    await Promise.all(
+      this.elements.map(element => this.commitParametersToVariantParameterizable(parameters, element, 'elements'))
+    );
+  }
+
+  /**
+   * Commits given parameters to all {@link ViewerLight}s.
+   */
+  protected async commitParametersToViewerLights(parameters: ParameterBag) {
+    await Promise.all(
+      this.viewerLights.map(viewerLight =>
+        this.commitParametersToVariantParameterizable(parameters, viewerLight, 'lights')
+      )
+    );
+  }
+
+  /**
+   * Commits given parameters to a {@link VariantParameterizable} and updates the according definition with given
+   * key in the {@link StructureJson}. The `definitionKey` "elements" for example will update the definition in
+   * `this.structureJson.elements`.
+   */
+  protected async commitParametersToVariantParameterizable(
+    parameters: ParameterBag,
+    parameterizable: VariantParameterizable,
+    definitionKey: string
+  ): Promise<ParameterObservable> {
+    const initialDefinition = get(this._structureJson, definitionKey)[parameterizable.name];
+    let initialDefinitionStr = JSON.stringify(initialDefinition);
+    const _parameters: ParameterBag = {};
+    for (const parameter in parameters) {
+      const dpp = DottedPath.create(parameter);
+      if (dpp.shiftPart() !== parameterizable.name) {
+        continue;
+      }
+      // we got a parameterizable ("element") parameter
+      let parameterValue = parameters[parameter];
+      const parameterizableParameter = dpp.path;
+      // If the variant is explicitly hidden, we must not override the visibility with element parameters. We need
+      // an exception for visibility to avoid overloading already applied element parameters with element parameters
+      // defined in the variant spec ("dotted parameters").
+      // @see https://github.com/Combeenation/3d-viewer/issues/44
+      if (parameterizableParameter === Parameter.VISIBLE && parameters[Parameter.VISIBLE] === false) {
+        parameterValue = false;
+      }
+      _parameters[parameterizableParameter] = parameterValue;
+      const search = new RegExp(`\\$\\{${parameterizableParameter}\\}`, 'g');
+      initialDefinitionStr = initialDefinitionStr.replace(search, parameterValue.toString());
+    }
+    const definition = get(this.structureJson, definitionKey);
+    definition[this.name] = JSON.parse(initialDefinitionStr);
+    set(this.structureJson, definitionKey, definition);
+    return await parameterizable.commitParameters(_parameters);
+  }
+
+  /**
+   * Commits given {@link Parameter} to the {@link Variant}'s {@link Element}s.
+   */
+  protected async commitParameterToElements(parameter: string, value: ParameterValue): Promise<Variant> {
+    const promises = [];
+    for (const element of this.elements) {
+      const paramShowsVariant = Parameter.VISIBLE === parameter && value;
+
+      // Fixes https://combeenation.youtrack.cloud/issue/CB-7773
+      // Don't enable/show the variants element if it is explicitly hidden via its element parameters.
+      // E.g. via spec:
+      // ```
+      // variants: {
+      //   theVariant: {
+      //     elements: {
+      //       Main: ['root.main'],
+      //       Secondary: ['root.secondary'],
+      //     },
+      //     parameters: {
+      //       // !!! The element `Secondary` should **not** be enabled when its containing variant is enabled !!!
+      //       'Secondary.visible': false,
+      //     }
+      //   }
+      // }
+      // ```
+      const elVisibleParamPath = DottedPath.create([element.name, Parameter.VISIBLE]).toString();
+      const elVisibleParamValue = this.inheritedParameters[elVisibleParamPath];
+      const elVisibleParamValueParsed = elVisibleParamValue && Parameter.parseBoolean(elVisibleParamValue);
+      const elIsHiddenViaParams = elVisibleParamValueParsed === false;
+      if (paramShowsVariant && elIsHiddenViaParams) continue;
+
+      // Fixes https://combeenation.youtrack.cloud/issue/CB-7809
+      // Apply element material before showing the element to prevent loading of the elements "original" material which
+      // is never shown when "overwritten" by elements material param.
+      const elMaterialParamPath = DottedPath.create([element.name, Parameter.MATERIAL]).toString();
+      const elMaterialParamValue = this.inheritedParameters[elMaterialParamPath];
+      if (paramShowsVariant && elMaterialParamValue) {
+        await element.commitParameter(Parameter.MATERIAL, elMaterialParamValue);
+      }
+
+      promises.push(element.commitParameter(parameter, value));
+    }
+    await Promise.all(promises);
+    return this;
+  }
+
+  /**
+   * Commits given {@link Parameter} to the {@link Variant}'s {@link Element}s.
+   */
+  protected async commitParameterToViewerLights(parameter: string, value: ParameterValue): Promise<Variant> {
+    const promises = [];
+    for (const viewerLight of this.viewerLights) {
+      promises.push(viewerLight.commitParameter(parameter, value));
+    }
+    await Promise.all(promises);
+    return this;
+  }
+
+  /**
+   * Adds the default {@link ParameterObserver}s which are called every time {@link commitParameters} is called.
+   */
+  protected addParameterObservers(): Variant {
+    this._parameterObservers.set(Parameter.VISIBLE, [
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        await variant.commitParameterToElements(Parameter.VISIBLE, newValue);
+        await variant.commitParameterToViewerLights(Parameter.VISIBLE, newValue);
+      },
+    ]);
+    this._parameterObservers.set(Parameter.SCALING, [
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        await variant.commitParameterToElements(Parameter.SCALING, newValue);
+        await variant.commitParameterToViewerLights(Parameter.SCALING, newValue);
+      },
+    ]);
+    this._parameterObservers.set(Parameter.MATERIAL, [
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        await variant.commitParameterToElements(Parameter.MATERIAL, newValue);
+      },
+    ]);
+    this._parameterObservers.set(Parameter.MATERIAL_COLOR, [
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        await variant.commitParameterToElements(Parameter.MATERIAL_COLOR, newValue);
+      },
+    ]);
+    this._parameterObservers.set(Parameter.MATERIAL_METALLNESS, [
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        await variant.commitParameterToElements(Parameter.MATERIAL_METALLNESS, newValue);
+      },
+    ]);
+    this._parameterObservers.set(Parameter.MATERIAL_ROUGHNESS, [
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        await variant.commitParameterToElements(Parameter.MATERIAL_ROUGHNESS, newValue);
+      },
+    ]);
+    this._parameterObservers.set(Parameter.HIGHLIGHT_COLOR, [
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        await variant.commitParameterToElements(Parameter.HIGHLIGHT_COLOR, newValue);
+      },
+    ]);
+    this._parameterObservers.set(Parameter.HIGHLIGHTED, [
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        await variant.commitParameterToElements(Parameter.HIGHLIGHTED, newValue);
+      },
+    ]);
+    this._parameterObservers.set(Parameter.POSITION, [
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        await variant.commitParameterToElements(Parameter.POSITION, newValue);
+        await variant.commitParameterToViewerLights(Parameter.POSITION, newValue);
+      },
+    ]);
+    this._parameterObservers.set(Parameter.ROTATION, [
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        await variant.commitParameterToElements(Parameter.ROTATION, newValue);
+        await variant.commitParameterToViewerLights(Parameter.ROTATION, newValue);
+      },
+    ]);
+    this._parameterObservers.set(Parameter.CAST_SHADOW, [
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        await variant.commitParameterToElements(Parameter.CAST_SHADOW, newValue);
+      },
+    ]);
+    this._parameterObservers.set(Parameter.CAST_SHADOW_FROM_LIGHTS, [
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        await variant.commitParameterToElements(Parameter.CAST_SHADOW_FROM_LIGHTS, newValue);
+      },
+    ]);
+    this._parameterObservers.set(Parameter.RECEIVE_SHADOWS, [
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
+        await variant.commitParameterToElements(Parameter.RECEIVE_SHADOWS, newValue);
+      },
+    ]);
+    return this;
+  }
+
+  /**
+   * Creates {@link Element}s and clones nodes into them.
+   */
+  protected async createElements(forInstance?: string): Promise<Variant> {
+    this.createElementDefinitionsIfNotExist();
+    for (const name in this.structureJson.elements || {}) {
+      this.elements.push(await Element.create(this, name));
+    }
+    // inject node meta to all inherited elements
+    // we do this to inject the deepest and most concrete variant information to all cloned nodes in the tree
+    this.inheritedElements.forEach(element =>
+      element.nodes.forEach(node => injectNodeMetadata(node, { variant: this, variantParameterizable: element }))
+    );
+    return this;
+  }
+
+  /**
+   * Creates {@link ViewerLight}s.
+   */
+  protected async createViewerLights(): Promise<Variant> {
+    for (const name in this.structureJson.lights || {}) {
+      this.viewerLights.push(await ViewerLight.create(this, name));
+    }
+    this.inheritedViewerLights.forEach(viewerLight => {
+      injectNodeMetadata(viewerLight.light, { variant: this, variantParameterizable: viewerLight });
+    });
+    return this;
+  }
+
+  /**
+   * Bootstrapping for parameters. It sets the `parametersInitialized` to true for all ancestors.
+   */
+  protected async bootstrapParameters(parameters?: ParameterBag): Promise<Variant> {
+    await this.commitParameters(merge(cloneDeep(this.parameters), parameters));
+    concat(this.ancestors, this).forEach(ancestor => (ancestor.parametersInitialized = true));
+    return this;
+  }
+
+  /**
+   * Ensures there is at least one "Main" {@link Element} for the {@link Variant} with all "root nodes" defined in path.
+   */
+  protected createElementDefinitionsIfNotExist() {
+    if (this._structureJson.elements || this.inheritedNodes.length === 0) {
+      return;
+    }
+    this._structureJson.elements = {
+      Main: { paths: { include: this.inheritedNodes.map(node => node.metadata.dottedPath.path) } },
+    };
+    this.structureJson.elements = cloneDeep(this._structureJson.elements);
+  }
+}