@combeenation/3d-viewer 9.0.0 → 9.0.1

package/src/api/classes/parameter.ts

@@ -1,670 +1,686 @@
-import { ViewerError, ViewerErrorIds } from './viewerError';
-import { Color3 } from '@babylonjs/core/Maths/math.color';
-import { Vector3 } from '@babylonjs/core/Maths/math.vector';
-import { capitalize, get, isEmpty, isNumber, isString } from 'lodash-es';
-
-/**
- * This `Parameter` class defines all parameters that can be consumed and committed by a {@link ParameterObservable}.
- * Use {@link ParameterObservable.addParameterObserver} or {@link ParameterObservable.commitParameters} to either add or
- * commit parameters on your observable objects.
- */
-export class Parameter {
-  /**
-   * Constructor.
-   */
-  private constructor() {}
-
-  /**
-   * Mutates the visibility. Helper methods are {@link VariantParameterizable.show} and
-   * {@link VariantParameterizable.hide}. Getter and setter is {@link VariantParameterizable.visible}.
-   *
-   * Scopes:
-   * * {@link Element}
-   * * {@link Variant}
-   * * {@link ViewerLight} Available for all light types
-   *
-   * @parser {@link parseBoolean}
-   */
-  public static readonly VISIBLE = 'visible';
-
-  /**
-   * Stretches or compresses some meshes. Getter and setter is {@link VariantParameterizable.scaling}.
-   *
-   * Scopes:
-   * * {@link Element}
-   * * {@link Variant}
-   *
-   * @parser {@link parseScaling}
-   */
-  public static readonly SCALING = 'scaling';
-
-  /**
-   * Mutates the material. Getter and setter is {@link VariantParameterizable.material}. The value of this parameter
-   * represents the ID of a baked-in glTF or custom created material in the {@link Variant} tree.
-   *
-   * Scopes:
-   * * {@link Element}
-   * * {@link Variant}
-   *
-   * @parser string
-   */
-  public static readonly MATERIAL = 'material';
-
-  /**
-   * Mutates the material color.
-   *
-   * Scopes:
-   * * {@link Element}
-   * * {@link Variant}
-   *
-   * @parser {@link parseColor}
-   */
-  public static readonly MATERIAL_COLOR = 'material.color';
-
-  /**
-   * Mutates the material metallness.
-   *
-   * Scopes:
-   * * {@link Element}
-   * * {@link Variant}
-   *
-   * @parser {@link parseNumber}
-   */
-  public static readonly MATERIAL_METALLNESS = 'material.metallness';
-
-  /**
-   * Mutates the material roughness.
-   *
-   * Scopes:
-   * * {@link Element}
-   * * {@link Variant}
-   *
-   * @parser {@link parseNumber}
-   */
-  public static readonly MATERIAL_ROUGHNESS = 'material.roughness';
-
-  /**
-   * Mutates whether a highlight layer should be enabled.
-   *
-   * Scopes:
-   * * {@link Element}
-   * * {@link Variant}
-   *
-   * @parser {@link parseBoolean}
-   */
-  public static readonly HIGHLIGHT_ENABLED = 'highlight.enabled';
-
-  /**
-   * Changes the highlight color.
-   *
-   * Scopes:
-   * * {@link Element}
-   * * {@link Variant}
-   *
-   * @parser {@link parseColor}
-   */
-  public static readonly HIGHLIGHT_COLOR = 'highlight.color';
-
-  /**
-   * Mutates the highlighted state. Getter and setter is {@link VariantParameterizable.highlighted}.
-   *
-   * Scopes:
-   * * {@link Element}
-   * * {@link Variant}
-   *
-   * @parser {@link parseBoolean}
-   */
-  public static readonly HIGHLIGHTED = 'highlighted';
-
-  /**
-   * Mutates the position relative to its origin position. Getter and setter is {@link VariantParameterizable.position}.
-   *
-   * Scopes:
-   * * {@link Element}
-   * * {@link Variant}
-   * * {@link ViewerLight} Available for [PointLight](https://doc.babylonjs.com/typedoc/classes/babylon.pointlight#position), [SpotLight](https://doc.babylonjs.com/typedoc/classes/babylon.spotlight#position), [DirectionalLight](https://doc.babylonjs.com/typedoc/classes/babylon.directionallight#position)
-   *
-   * @parser {@link parseVector}
-   */
-  public static readonly POSITION = 'position';
-
-  /**
-   * Mutates the rotation relative to its origin rotation. Getter and setter is {@link VariantParameterizable.rotation}.
-   *
-   * Scopes:
-   * * {@link Element}
-   * * {@link Variant}
-   *
-   * @parser {@link parseRotation}
-   */
-  public static readonly ROTATION = 'rotation';
-
-  /**
-   * Mutates the color.
-   *
-   * Scopes:
-   * * {@link Material} via {@link TagManager}
-   *
-   * @parser {@link parseColor}
-   */
-  public static readonly COLOR = 'color';
-
-  /**
-   * Mutates the metallic.
-   *
-   * Scopes:
-   * * {@link Material} via {@link TagManager}
-   *
-   * @parser {@link parseNumber}
-   */
-  public static readonly METALLIC = 'metallic';
-
-  /**
-   * Mutates the texture of a material, based on an svg string, image path or image data.
-   *
-   * Scopes:
-   * * {@link Material} via {@link TagManager}
-   *
-   */
-  public static readonly PAINTABLE = 'paintable';
-
-  /**
-   * Mutates the roughness.
-   *
-   * Scopes:
-   * * {@link Material} via {@link TagManager}
-   *
-   * @parser {@link parseNumber}
-   */
-  public static readonly ROUGHNESS = 'roughness';
-
-  /**
-   * Mutates whether a shadow should be casted or not.
-   *
-   * Scopes:
-   * * {@link Element}
-   * * {@link Variant}
-   *
-   * @parser {@link parseBoolean}
-   */
-  public static readonly CAST_SHADOW = 'castShadow';
-
-  /**
-   * Mutates from which lights a shadow should be casted.
-   *
-   * Scopes:
-   * * {@link Element}
-   * * {@link Variant}
-   *
-   * @parser {@link parseCommaSeparatedList}
-   */
-  public static readonly CAST_SHADOW_FROM_LIGHTS = 'castShadow.fromLights';
-
-  /**
-   * Mutates whether to receive shadows or not.
-   *
-   * Scopes:
-   * * {@link Element}
-   * * {@link Variant}
-   *
-   * @parser {@link parseBoolean}
-   */
-  public static readonly RECEIVE_SHADOWS = 'receiveShadows';
-
-  /**
-   * Mutates the intensity of Lights.
-   *
-   * Scopes:
-   * * {@link ViewerLight} Available for [PointLight](https://doc.babylonjs.com/typedoc/classes/babylon.pointlight#intensity), [SpotLight](https://doc.babylonjs.com/typedoc/classes/babylon.spotlight#intensity), [DirectionalLight](https://doc.babylonjs.com/typedoc/classes/babylon.directionallight#intensity), [HemisphericLight](https://doc.babylonjs.com/typedoc/classes/babylon.hemisphericlight#intensity)
-   *
-   * @parser {@link parseNumber}
-   */
-  public static readonly INTENSITY = 'intensity';
-
-  /**
-   * Mutates the direction of Lights.
-   *
-   * Scopes:
-   * * {@link ViewerLight} Available for [PointLight](https://doc.babylonjs.com/typedoc/classes/babylon.pointlight#direction), [SpotLight](https://doc.babylonjs.com/typedoc/classes/babylon.spotlight#direction), [DirectionalLight](https://doc.babylonjs.com/typedoc/classes/babylon.directionallight#direction), [HemisphericLight](https://doc.babylonjs.com/typedoc/classes/babylon.hemisphericlight#direction)
-   *
-   * @parser {@link parseNumber}
-   */
-  public static readonly DIRECTION = 'direction';
-
-  /**
-   * Mutates the angle of Lights.
-   *
-   * Scopes:
-   * * {@link ViewerLight} Available for [SpotLight](https://doc.babylonjs.com/typedoc/classes/babylon.spotlight#angle)
-   *
-   * @parser {@link parseNumber}
-   */
-  public static readonly ANGLE = 'angle';
-
-  /**
-   * Mutates the exponent of Lights.
-   *
-   * Scopes:
-   * * {@link ViewerLight} Available for [SpotLight](https://doc.babylonjs.com/typedoc/classes/babylon.spotlight#exponent)
-   *
-   * @parser {@link parseNumber}
-   */
-  public static readonly EXPONENT = 'exponent';
-
-  /**
-   * Mutates the diffuse color of Lights.
-   *
-   * Scopes:
-   * * {@link ViewerLight} Available for [PointLight](https://doc.babylonjs.com/typedoc/classes/babylon.pointlight#diffuse), [SpotLight](https://doc.babylonjs.com/typedoc/classes/babylon.spotlight#diffuse), [DirectionalLight](https://doc.babylonjs.com/typedoc/classes/babylon.directionallight#diffuse), [HemisphericLight](https://doc.babylonjs.com/typedoc/classes/babylon.hemisphericlight#diffuse)
-   *
-   * @parser {@link parseNumber}
-   */
-  public static readonly DIFFUSE = 'diffuse';
-
-  /**
-   * Mutates the specular color of Lights.
-   *
-   * Scopes:
-   * * {@link ViewerLight} Available for [PointLight](https://doc.babylonjs.com/typedoc/classes/babylon.pointlight#specular), [SpotLight](https://doc.babylonjs.com/typedoc/classes/babylon.spotlight#specular), [DirectionalLight](https://doc.babylonjs.com/typedoc/classes/babylon.directionallight#specular), [HemisphericLight](https://doc.babylonjs.com/typedoc/classes/babylon.hemisphericlight#specular)
-   *
-   * @parser {@link parseNumber}
-   */
-  public static readonly SPECULAR = 'specular';
-
-  /**
-   * Sets the environment. See [BABYLON.Scene.environmentTexture](https://doc.babylonjs.com/typedoc/classes/BABYLON.Scene#environmentTexture).
-   *
-   * Usually the URL to an `*.env` file.
-   *
-   * See [environment page](./../pages/Documentation/Environment.html) for details on how to use this.
-   *
-   * Scopes:
-   * * {@link SceneManager}
-   *
-   * @parser string
-   */
-  public static readonly ENVIRONMENT = 'environment';
-
-  /**
-   * Sets [BABYLON.Scene.clearColor](https://doc.babylonjs.com/typedoc/classes/BABYLON.Scene#clearColor)
-   *
-   * See [environment page](./../pages/Documentation/Environment.html) for details on how to use this.
-   *
-   * Scopes:
-   * * {@link SceneManager}
-   *
-   * @parser {@link parseColor}
-   */
-  public static readonly ENVIRONMENT_COLOR = 'environment.color';
-
-  /**
-   * Rotates connected textures, i.e. IBL, reflection, background, ...
-   * Rotation angle in degree.
-   *
-   * See [environment page](./../pages/Documentation/Environment.html) for details on how to use this.
-   *
-   * Scopes:
-   * * {@link SceneManager}
-   *
-   * @parser {@link parseNumber}
-   */
-  public static readonly ENVIRONMENT_ROTATION = 'environment.rotation';
-
-  /**
-   * Intensity of IBL. Defaults to 1, usually between 0 & 2.
-   *
-   * See [environment page](./../pages/Documentation/Environment.html) for details on how to use this.
-   *
-   * Scopes:
-   * * {@link SceneManager}
-   *
-   * @parser {@link parseNumber}
-   */
-  public static readonly ENVIRONMENT_INTENSITY = 'environment.intensity';
-
-  /**
-   * Background texture on a [PhotoDome](https://doc.babylonjs.com/divingDeeper/environment/360PhotoDome).
-   * Just background, no IBL or reflection.
-   *
-   * Recommended format is `*.jpg`. HDR files are not supported as background but can be converted to `*.jpg` using
-   * tools like Photoshop, Gimp or various free online converters.
-   *
-   * See [environment page](./../pages/Documentation/Environment.html) for details on how to use this.
-   *
-   * Scopes:
-   * * {@link SceneManager}
-   *
-   * @parser string
-   */
-  public static readonly ENVIRONMENT_BACKGROUND = 'environment.background';
-
-  /**
-   * If `true`, sets a `scene.environmentTexture` and creates a *BackgroundHelper* Node (via
-   * [scene.createDefaultEnvironment](https://doc.babylonjs.com/typedoc/classes/BABYLON.Scene#createDefaultEnvironment))
-   * with two subnodes/meshes:
-   * - BackgroundPlane
-   * - BackgroundSkybox
-   *
-   * The value of this parameter is ignored if {@link ENVIRONMENT_BACKGROUND} is also set.
-   *
-   * See [environment page](./../pages/Documentation/Environment.html) for details on how to use this.
-   *
-   * Scopes:
-   * * {@link SceneManager}
-   *
-   * @parser {@link parseBoolean}
-   */
-  public static readonly ENVIRONMENT_USEDEFAULT = 'environment.usedefault';
-
-  /**
-   * The {@link ParameterDeclarations} for all parameters in this class.
-   */
-  public static get declarations(): ParameterDeclarations {
-    return {
-      [Parameter.VISIBLE]: { type: 'boolean', parser: Parameter.parseBoolean },
-      [Parameter.SCALING]: { type: 'number', parser: Parameter.parseNumber },
-      [Parameter.POSITION]: { type: 'vector', parser: Parameter.parseVector },
-      [Parameter.ROTATION]: { type: 'vector', parser: Parameter.parseVector },
-      [Parameter.HIGHLIGHTED]: { type: 'boolean', parser: Parameter.parseBoolean },
-      [Parameter.MATERIAL]: { type: 'string' },
-      [Parameter.MATERIAL_COLOR]: { type: 'color', parser: Parameter.parseColor },
-      [Parameter.MATERIAL_METALLNESS]: { type: 'number', parser: Parameter.parseNumber },
-      [Parameter.MATERIAL_ROUGHNESS]: { type: 'number', parser: Parameter.parseNumber },
-      [Parameter.HIGHLIGHT_ENABLED]: { type: 'boolean', parser: Parameter.parseBoolean },
-      [Parameter.HIGHLIGHT_COLOR]: { type: 'color', parser: Parameter.parseColor },
-      [Parameter.HIGHLIGHTED]: { type: 'boolean', parser: Parameter.parseBoolean },
-      [Parameter.CAST_SHADOW]: { type: 'boolean', parser: Parameter.parseBoolean },
-      [Parameter.CAST_SHADOW_FROM_LIGHTS]: { type: 'csl', parser: Parameter.parseCommaSeparatedList },
-      [Parameter.RECEIVE_SHADOWS]: { type: 'boolean', parser: Parameter.parseBoolean },
-      [Parameter.INTENSITY]: { type: 'number', parser: Parameter.parseNumber },
-      [Parameter.DIRECTION]: { type: 'vector', parser: Parameter.parseVector },
-      [Parameter.ANGLE]: { type: 'number', parser: Parameter.parseNumber },
-      [Parameter.EXPONENT]: { type: 'number', parser: Parameter.parseNumber },
-      [Parameter.DIFFUSE]: { type: 'color', parser: Parameter.parseColor },
-      [Parameter.SPECULAR]: { type: 'color', parser: Parameter.parseColor },
-      [Parameter.ENVIRONMENT]: { type: 'string' },
-      [Parameter.ENVIRONMENT_COLOR]: { type: 'color', parser: Parameter.parseColor },
-      [Parameter.ENVIRONMENT_ROTATION]: { type: 'number', parser: Parameter.parseNumber },
-      [Parameter.ENVIRONMENT_INTENSITY]: { type: 'number', parser: Parameter.parseNumber },
-      [Parameter.ENVIRONMENT_BACKGROUND]: { type: 'string' },
-      [Parameter.ENVIRONMENT_USEDEFAULT]: { type: 'boolean', parser: Parameter.parseBoolean },
-    };
-  }
-
-  /**
-   * The default {@link ParameterValue}s returned as {@link ParameterBag} for a set of parameters in this class.
-   */
-  public static get defaultValues(): ParameterBag {
-    return {
-      [Parameter.SCALING]: '(1, 1, 1)',
-      [Parameter.POSITION]: '(0, 0, 0)',
-      [Parameter.ROTATION]: '(0, 0, 0)',
-    };
-  }
-
-  /**
-   * Gets the {@link ParameterDeclaration} for a given {@link Parameter} declared in this class.
-   */
-  public static getDeclaration(parameter: string): ParameterDeclaration {
-    return Parameter.declarations[parameter];
-  }
-
-  /**
-   * Gets the default {@link ParameterValue} for a given {@link Parameter} declared in this class.
-   */
-  public static getDefaultValue(parameter: string): ParameterValue {
-    return Parameter.defaultValues[parameter];
-  }
-
-  /**
-   * All parameters defined in this class.
-   */
-  public static get all() {
-    const all: string[] = [];
-    for (const parameter in Parameter) {
-      const property = Object.getOwnPropertyDescriptor(Parameter, parameter);
-      if (parameter.toUpperCase() === parameter && property && isString(property.value)) {
-        all.push(property.value);
-      }
-    }
-    return all;
-  }
-
-  /**
-   * Asserts whether given parameter is declared and valid.
-   */
-  public static assertParameter(parameterDeclaration: ParameterDeclarations, parameter: string, value: ParameterValue) {
-    if (!(parameter in parameterDeclaration)) {
-      // This is a valid case since we are not able to check parameters that are not declared.
-      // We just ignore parameters that are not declared.
-      return;
-    }
-    const declaration = parameterDeclaration[parameter];
-    const genericError = `"${value}" is not a valid value for parameter "${parameter}" of type "${declaration.type}".`;
-    if (declaration.parser) {
-      try {
-        declaration.parser(value);
-      } catch (e: any) {
-        throw new ViewerError({
-          id: ViewerErrorIds.InvalidParameterValue,
-          message: `${genericError} ${e.message}`,
-        });
-      }
-    }
-    switch (declaration.type) {
-      case 'select':
-        if (!declaration.options) {
-          throw new ViewerError({
-            id: ViewerErrorIds.UnknownParameterOption,
-            message: `No options defined for parameter declaration "${parameter}" of type "${declaration.type}".`,
-          });
-        }
-        if (declaration.options.indexOf(value) === -1) {
-          throw Error(genericError + ` Valid values are: "${declaration.options.join('", "')}".`);
-        }
-        break;
-    }
-  }
-
-  /**
-   * Parses given {@link ParameterBag} with given {@link ParameterDeclarations}.
-   */
-  public static parseFromDeclarations(
-    declarations: ParameterDeclarations,
-    parameterBag: ParameterBag
-  ): ParsedParameterBag {
-    const parameters: ParsedParameterBag = {};
-    for (const parameter in parameterBag) {
-      const value = get(parameterBag, parameter);
-      parameters[parameter] = value;
-      const declaration: ParameterDeclaration = declarations[parameter];
-      if (declaration) {
-        if (!isEmpty(value) && declaration.parser) {
-          parameters[parameter] = declaration.parser(value);
-        }
-      }
-    }
-    return parameters;
-  }
-
-  /**
-   * Parses a string of format `'(x,y,z)'` to a `Vector3`.
-   */
-  public static parseVector(value: ParameterValue): Vector3 {
-    if (!isString(value)) {
-      throw new Error(`Unable to convert "${value}" into a Vector: not a string.`);
-    }
-    let cleanedValue = value.split(' ').join('');
-    if (cleanedValue.startsWith('(') && cleanedValue.endsWith(')')) {
-      cleanedValue = cleanedValue.substring(1, cleanedValue.length - 1);
-      const [x, y, z] = cleanedValue.split(',').map(value => parseFloat(value));
-      return new Vector3(x, y, z);
-    } else {
-      throw new Error(`Unable to parse "${value}" to a Vector: expected "(x,y,z)".`);
-    }
-  }
-
-  /**
-   * Stringifies a Vector3 to format `(x,y,z)`.
-   */
-  public static stringifyVector(value: Vector3): string {
-    return `(${value.x},${value.y},${value.z})`;
-  }
-
-  /**
-   * Parses a string of format `'(x,y,z)'` with angular degrees to a `Vector3` with rotation information in radians.
-   */
-  public static parseRotation(value: ParameterValue): Vector3 {
-    const rotation = Parameter.parseVector(value);
-    const deg2rad = function (deg: number) {
-      return (deg * Math.PI) / 180;
-    };
-    return rotation.set(deg2rad(rotation.x), deg2rad(rotation.y), deg2rad(rotation.z));
-  }
-
-  /**
-   * Parses a string of format `'(x,y,z)'` or a simple `number` to a `Vector3` for scaling.
-   */
-  public static parseScaling(value: ParameterValue): Vector3 {
-    let scaling = new Vector3();
-    if (isString(value)) {
-      const cleanedFactor = value.split(' ').join('');
-      if (cleanedFactor.startsWith('(') && cleanedFactor.endsWith(')')) {
-        scaling = Parameter.parseVector(cleanedFactor);
-      } else {
-        const _factor = parseFloat(value);
-        scaling = new Vector3(_factor, _factor, _factor);
-      }
-    } else if (isNumber(value)) {
-      scaling = new Vector3(value, value, value);
-    } else {
-      throw new Error(`Unable to convert "${value}" to a Vector: expected "(x,y,z)".`);
-    }
-    return scaling;
-  }
-
-  /**
-   * Parses a string of format `'#rrggbb'` or `'(r,g,b)'` to a `Color3`.
-   */
-  public static parseColor(value: ParameterValue): Color3 {
-    const cleanedValue = value.toString().split(' ').join('');
-    if (cleanedValue.startsWith('#')) {
-      return Color3.FromHexString(value.toString());
-    }
-    if (cleanedValue.startsWith('(') && cleanedValue.endsWith(')')) {
-      const rgb = cleanedValue.substring(1, cleanedValue.length - 1);
-      const [r, g, b] = rgb.split(',').map(value => parseFloat(value));
-      return Color3.FromInts(r, g, b);
-    }
-    const humanReadable = capitalize(cleanedValue);
-    // disable lint for this rule as there is no smoother option for checking static class functions (eg Color.Red())
-    // eslint-disable-next-line no-prototype-builtins
-    if (Color3.hasOwnProperty(humanReadable)) {
-      // @ts-ignore same as above
-      return Color3[humanReadable]();
-    }
-    throw new Error(
-      `Unable to parse "${value}" to a Color: expected "#rrggbb", "(r,g,b)" or any human readable property implemented in Color3.`
-    );
-  }
-
-  /**
-   * Parses a `boolean` string (`'true'`/`'1'` or `'false'`/`'0'`) or `number` (`1` or `0`) to a `boolean` or
-   * `undefined`.
-   */
-  public static parseBoolean(value: ParameterValue): boolean {
-    if (value.toString() === 'true' || value.toString() === '1') {
-      return true;
-    } else if (value.toString() === 'false' || value.toString() === '0') {
-      return false;
-    }
-    throw new Error(`Unable to parse "${value}" to a boolean.`);
-  }
-
-  /**
-   * Parses a number `string` to a `number`.
-   */
-  public static parseNumber(value: ParameterValue): number {
-    return parseFloat(value.toString());
-  }
-
-  /**
-   * Parses string defintion of a paintable into a paintable object.
-   * Here are some examples:
-   * - '{ "src": "pathToCertain.jpg", "uScale": 0.5 }' => default definition as JSON object
-   * - 'pathToCertain.jpg' => short hand definition, only contains source string
-   * - '{ "src": "pathToCertain.jpg", "uScale": -1, "vScale": -1, "uOffset": 0, "vOffset": 0 }' => full content,
-   *    paintable texture is flipped in both directions
-   * - '<svg>...</svg>' => SVG content can be used directly
-   * - { "src": "<svg>...</svg>", "uScale": 0.5 } => SVG in src property works as well
-   */
-  public static parsePaintableValue(value: ParameterValue): PaintableValue {
-    if (!isString(value)) {
-      throw new Error(`Unable to parse "${value}" to a PaintableValue: not a string.`);
-    }
-
-    const paintableValue: PaintableValue = { src: '' };
-    let valObj: { [key: string]: any } | null = null;
-
-    try {
-      valObj = JSON.parse(value);
-    } catch {
-      // use string directly
-      paintableValue.src = value;
-
-      if (value.startsWith('{')) {
-        // seems like the user tried to use a JSON string, as the input starts with {
-        throw new Error(`Unable to parse "${value}" to a PaintableValue: not a valid JSON string.`);
-      }
-    }
-
-    if (valObj) {
-      // input string is JSON, src attribute is required
-      if (!valObj.src) {
-        throw new Error(`Unable to parse "${value}" to a PaintableValue: property "src" is missing.`);
-      }
-
-      if (!isString(valObj.src)) {
-        throw new Error(`Unable to parse "${value}" to a PaintableValue: property "src" is not a string.`);
-      }
-
-      // split src and options
-      const { src, ...options } = valObj;
-      paintableValue.src = src;
-
-      // only forward valid paintable options
-      const validOptionKeys = ['uScale', 'vScale', 'uOffset', 'vOffset'];
-      const { validOptions, invalidKeys } = Object.entries(options).reduce(
-        (accRes, [curKey, curValue]) => {
-          const isValidKey = validOptionKeys.includes(curKey);
-          if (isValidKey) {
-            accRes.validOptions[curKey] = curValue;
-          } else {
-            accRes.invalidKeys.push(curKey);
-          }
-
-          return accRes;
-        },
-        { validOptions: {} as { [key: string]: any }, invalidKeys: [] as string[] }
-      );
-
-      if (invalidKeys.length) {
-        console.warn('parsePaintableValue: invalid paintable options provided: ' + invalidKeys.toString());
-      }
-
-      paintableValue.options = validOptions;
-    }
-
-    return paintableValue;
-  }
-
-  /**
-   * Parses a string with comma separated values to a list of strings.
-   */
-  public static parseCommaSeparatedList(value: ParameterValue): string[] {
-    return value
-      .toString()
-      .split(',')
-      .map(s => s.trim());
-  }
-}
+import { ViewerError, ViewerErrorIds } from './viewerError';
+import { Color3 } from '@babylonjs/core/Maths/math.color';
+import { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import { capitalize, get, isEmpty, isNumber, isString } from 'lodash-es';
+
+/**
+ * This `Parameter` class defines all parameters that can be consumed and committed by a {@link ParameterObservable}.
+ * Use {@link ParameterObservable.addParameterObserver} or {@link ParameterObservable.commitParameters} to either add or
+ * commit parameters on your observable objects.
+ */
+export class Parameter {
+  /**
+   * Constructor.
+   */
+  private constructor() {}
+
+  /**
+   * Mutates the visibility. Helper methods are {@link VariantParameterizable.show} and
+   * {@link VariantParameterizable.hide}. Getter and setter is {@link VariantParameterizable.visible}.
+   *
+   * Scopes:
+   * * {@link Element}
+   * * {@link Variant}
+   * * {@link ViewerLight} Available for all light types
+   *
+   * @parser {@link parseBoolean}
+   */
+  public static readonly VISIBLE = 'visible';
+
+  /**
+   * Stretches or compresses some meshes. Getter and setter is {@link VariantParameterizable.scaling}.
+   *
+   * Scopes:
+   * * {@link Element}
+   * * {@link Variant}
+   *
+   * @parser {@link parseScaling}
+   */
+  public static readonly SCALING = 'scaling';
+
+  /**
+   * Mutates the material. Getter and setter is {@link VariantParameterizable.material}. The value of this parameter
+   * represents the ID of a baked-in glTF or custom created material in the {@link Variant} tree.
+   *
+   * Scopes:
+   * * {@link Element}
+   * * {@link Variant}
+   *
+   * @parser string
+   */
+  public static readonly MATERIAL = 'material';
+
+  /**
+   * Mutates the material color.
+   *
+   * Scopes:
+   * * {@link Element}
+   * * {@link Variant}
+   *
+   * @parser {@link parseColor}
+   */
+  public static readonly MATERIAL_COLOR = 'material.color';
+
+  /**
+   * Mutates the material metallness.
+   *
+   * Scopes:
+   * * {@link Element}
+   * * {@link Variant}
+   *
+   * @parser {@link parseNumber}
+   */
+  public static readonly MATERIAL_METALLNESS = 'material.metallness';
+
+  /**
+   * Mutates the material roughness.
+   *
+   * Scopes:
+   * * {@link Element}
+   * * {@link Variant}
+   *
+   * @parser {@link parseNumber}
+   */
+  public static readonly MATERIAL_ROUGHNESS = 'material.roughness';
+
+  /**
+   * Mutates whether a highlight layer should be enabled.
+   *
+   * Scopes:
+   * * {@link Element}
+   * * {@link Variant}
+   *
+   * @parser {@link parseBoolean}
+   */
+  public static readonly HIGHLIGHT_ENABLED = 'highlight.enabled';
+
+  /**
+   * Changes the highlight color.
+   *
+   * Scopes:
+   * * {@link Element}
+   * * {@link Variant}
+   *
+   * @parser {@link parseColor}
+   */
+  public static readonly HIGHLIGHT_COLOR = 'highlight.color';
+
+  /**
+   * Mutates the highlighted state. Getter and setter is {@link VariantParameterizable.highlighted}.
+   *
+   * Scopes:
+   * * {@link Element}
+   * * {@link Variant}
+   *
+   * @parser {@link parseBoolean}
+   */
+  public static readonly HIGHLIGHTED = 'highlighted';
+
+  /**
+   * Mutates the position relative to its origin position. Getter and setter is {@link VariantParameterizable.position}.
+   *
+   * Scopes:
+   * * {@link Element}
+   * * {@link Variant}
+   * * {@link ViewerLight} Available for [PointLight](https://doc.babylonjs.com/typedoc/classes/babylon.pointlight#position), [SpotLight](https://doc.babylonjs.com/typedoc/classes/babylon.spotlight#position), [DirectionalLight](https://doc.babylonjs.com/typedoc/classes/babylon.directionallight#position)
+   *
+   * @parser {@link parseVector}
+   */
+  public static readonly POSITION = 'position';
+
+  /**
+   * Mutates the rotation relative to its origin rotation. Getter and setter is {@link VariantParameterizable.rotation}.
+   *
+   * Scopes:
+   * * {@link Element}
+   * * {@link Variant}
+   *
+   * @parser {@link parseRotation}
+   */
+  public static readonly ROTATION = 'rotation';
+
+  /**
+   * Mutates the color.
+   *
+   * Scopes:
+   * * {@link Material} via {@link TagManager}
+   *
+   * @parser {@link parseColor}
+   */
+  public static readonly COLOR = 'color';
+
+  /**
+   * Mutates the metallic.
+   *
+   * Scopes:
+   * * {@link Material} via {@link TagManager}
+   *
+   * @parser {@link parseNumber}
+   */
+  public static readonly METALLIC = 'metallic';
+
+  /**
+   * Paintables can be used to let the client/browser draw graphics on a 3d model by mutating the texture of a
+   * material.\
+   * For detailed information have a look at the [paintables](./../pages/documentation/Paintables.html) page.
+   *
+   * Also see {@link parsePaintable} for detailed information on which values you can pass to the `paintable`
+   * parameter.
+   *
+   * Scopes:
+   * * {@link Material} via {@link TagManager}
+   *
+   * @parser {@link parsePaintable}
+   *
+   */
+  public static readonly PAINTABLE = 'paintable';
+
+  /**
+   * Mutates the roughness.
+   *
+   * Scopes:
+   * * {@link Material} via {@link TagManager}
+   *
+   * @parser {@link parseNumber}
+   */
+  public static readonly ROUGHNESS = 'roughness';
+
+  /**
+   * Mutates whether a shadow should be casted or not.
+   *
+   * Scopes:
+   * * {@link Element}
+   * * {@link Variant}
+   *
+   * @parser {@link parseBoolean}
+   */
+  public static readonly CAST_SHADOW = 'castShadow';
+
+  /**
+   * Mutates from which lights a shadow should be casted.
+   *
+   * Scopes:
+   * * {@link Element}
+   * * {@link Variant}
+   *
+   * @parser {@link parseCommaSeparatedList}
+   */
+  public static readonly CAST_SHADOW_FROM_LIGHTS = 'castShadow.fromLights';
+
+  /**
+   * Mutates whether to receive shadows or not.
+   *
+   * Scopes:
+   * * {@link Element}
+   * * {@link Variant}
+   *
+   * @parser {@link parseBoolean}
+   */
+  public static readonly RECEIVE_SHADOWS = 'receiveShadows';
+
+  /**
+   * Mutates the intensity of Lights.
+   *
+   * Scopes:
+   * * {@link ViewerLight} Available for [PointLight](https://doc.babylonjs.com/typedoc/classes/babylon.pointlight#intensity), [SpotLight](https://doc.babylonjs.com/typedoc/classes/babylon.spotlight#intensity), [DirectionalLight](https://doc.babylonjs.com/typedoc/classes/babylon.directionallight#intensity), [HemisphericLight](https://doc.babylonjs.com/typedoc/classes/babylon.hemisphericlight#intensity)
+   *
+   * @parser {@link parseNumber}
+   */
+  public static readonly INTENSITY = 'intensity';
+
+  /**
+   * Mutates the direction of Lights.
+   *
+   * Scopes:
+   * * {@link ViewerLight} Available for [PointLight](https://doc.babylonjs.com/typedoc/classes/babylon.pointlight#direction), [SpotLight](https://doc.babylonjs.com/typedoc/classes/babylon.spotlight#direction), [DirectionalLight](https://doc.babylonjs.com/typedoc/classes/babylon.directionallight#direction), [HemisphericLight](https://doc.babylonjs.com/typedoc/classes/babylon.hemisphericlight#direction)
+   *
+   * @parser {@link parseNumber}
+   */
+  public static readonly DIRECTION = 'direction';
+
+  /**
+   * Mutates the angle of Lights.
+   *
+   * Scopes:
+   * * {@link ViewerLight} Available for [SpotLight](https://doc.babylonjs.com/typedoc/classes/babylon.spotlight#angle)
+   *
+   * @parser {@link parseNumber}
+   */
+  public static readonly ANGLE = 'angle';
+
+  /**
+   * Mutates the exponent of Lights.
+   *
+   * Scopes:
+   * * {@link ViewerLight} Available for [SpotLight](https://doc.babylonjs.com/typedoc/classes/babylon.spotlight#exponent)
+   *
+   * @parser {@link parseNumber}
+   */
+  public static readonly EXPONENT = 'exponent';
+
+  /**
+   * Mutates the diffuse color of Lights.
+   *
+   * Scopes:
+   * * {@link ViewerLight} Available for [PointLight](https://doc.babylonjs.com/typedoc/classes/babylon.pointlight#diffuse), [SpotLight](https://doc.babylonjs.com/typedoc/classes/babylon.spotlight#diffuse), [DirectionalLight](https://doc.babylonjs.com/typedoc/classes/babylon.directionallight#diffuse), [HemisphericLight](https://doc.babylonjs.com/typedoc/classes/babylon.hemisphericlight#diffuse)
+   *
+   * @parser {@link parseNumber}
+   */
+  public static readonly DIFFUSE = 'diffuse';
+
+  /**
+   * Mutates the specular color of Lights.
+   *
+   * Scopes:
+   * * {@link ViewerLight} Available for [PointLight](https://doc.babylonjs.com/typedoc/classes/babylon.pointlight#specular), [SpotLight](https://doc.babylonjs.com/typedoc/classes/babylon.spotlight#specular), [DirectionalLight](https://doc.babylonjs.com/typedoc/classes/babylon.directionallight#specular), [HemisphericLight](https://doc.babylonjs.com/typedoc/classes/babylon.hemisphericlight#specular)
+   *
+   * @parser {@link parseNumber}
+   */
+  public static readonly SPECULAR = 'specular';
+
+  /**
+   * Sets the environment. See [BABYLON.Scene.environmentTexture](https://doc.babylonjs.com/typedoc/classes/BABYLON.Scene#environmentTexture).
+   *
+   * Usually the URL to an `*.env` file.
+   *
+   * See [environment page](./../pages/documentation/Environment.html) for details on how to use this.
+   *
+   * Scopes:
+   * * {@link SceneManager}
+   *
+   * @parser string
+   */
+  public static readonly ENVIRONMENT = 'environment';
+
+  /**
+   * Sets [BABYLON.Scene.clearColor](https://doc.babylonjs.com/typedoc/classes/BABYLON.Scene#clearColor)
+   *
+   * See [environment page](./../pages/documentation/Environment.html) for details on how to use this.
+   *
+   * Scopes:
+   * * {@link SceneManager}
+   *
+   * @parser {@link parseColor}
+   */
+  public static readonly ENVIRONMENT_COLOR = 'environment.color';
+
+  /**
+   * Rotates connected textures, i.e. IBL, reflection, background, ...
+   * Rotation angle in degree.
+   *
+   * See [environment page](./../pages/documentation/Environment.html) for details on how to use this.
+   *
+   * Scopes:
+   * * {@link SceneManager}
+   *
+   * @parser {@link parseNumber}
+   */
+  public static readonly ENVIRONMENT_ROTATION = 'environment.rotation';
+
+  /**
+   * Intensity of IBL. Defaults to 1, usually between 0 & 2.
+   *
+   * See [environment page](./../pages/documentation/Environment.html) for details on how to use this.
+   *
+   * Scopes:
+   * * {@link SceneManager}
+   *
+   * @parser {@link parseNumber}
+   */
+  public static readonly ENVIRONMENT_INTENSITY = 'environment.intensity';
+
+  /**
+   * Background texture on a [PhotoDome](https://doc.babylonjs.com/divingDeeper/environment/360PhotoDome).
+   * Just background, no IBL or reflection.
+   *
+   * Recommended format is `*.jpg`. HDR files are not supported as background but can be converted to `*.jpg` using
+   * tools like Photoshop, Gimp or various free online converters.
+   *
+   * See [environment page](./../pages/documentation/Environment.html) for details on how to use this.
+   *
+   * Scopes:
+   * * {@link SceneManager}
+   *
+   * @parser string
+   */
+  public static readonly ENVIRONMENT_BACKGROUND = 'environment.background';
+
+  /**
+   * If `true`, sets a `scene.environmentTexture` and creates a *BackgroundHelper* Node (via
+   * [scene.createDefaultEnvironment](https://doc.babylonjs.com/typedoc/classes/BABYLON.Scene#createDefaultEnvironment))
+   * with two subnodes/meshes:
+   * - BackgroundPlane
+   * - BackgroundSkybox
+   *
+   * The value of this parameter is ignored if {@link ENVIRONMENT_BACKGROUND} is also set.
+   *
+   * See [environment page](./../pages/documentation/Environment.html) for details on how to use this.
+   *
+   * Scopes:
+   * * {@link SceneManager}
+   *
+   * @parser {@link parseBoolean}
+   */
+  public static readonly ENVIRONMENT_USEDEFAULT = 'environment.usedefault';
+
+  /**
+   * The {@link ParameterDeclarations} for all parameters in this class.
+   */
+  public static get declarations(): ParameterDeclarations {
+    return {
+      [Parameter.VISIBLE]: { type: 'boolean', parser: Parameter.parseBoolean },
+      [Parameter.SCALING]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.POSITION]: { type: 'vector', parser: Parameter.parseVector },
+      [Parameter.ROTATION]: { type: 'vector', parser: Parameter.parseVector },
+      [Parameter.HIGHLIGHTED]: { type: 'boolean', parser: Parameter.parseBoolean },
+      [Parameter.MATERIAL]: { type: 'string' },
+      [Parameter.MATERIAL_COLOR]: { type: 'color', parser: Parameter.parseColor },
+      [Parameter.MATERIAL_METALLNESS]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.MATERIAL_ROUGHNESS]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.HIGHLIGHT_ENABLED]: { type: 'boolean', parser: Parameter.parseBoolean },
+      [Parameter.HIGHLIGHT_COLOR]: { type: 'color', parser: Parameter.parseColor },
+      [Parameter.COLOR]: { type: 'color', parser: Parameter.parseColor },
+      [Parameter.METALLIC]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.ROUGHNESS]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.PAINTABLE]: { type: 'paintable', parser: Parameter.parsePaintable },
+      [Parameter.HIGHLIGHTED]: { type: 'boolean', parser: Parameter.parseBoolean },
+      [Parameter.CAST_SHADOW]: { type: 'boolean', parser: Parameter.parseBoolean },
+      [Parameter.CAST_SHADOW_FROM_LIGHTS]: { type: 'csl', parser: Parameter.parseCommaSeparatedList },
+      [Parameter.RECEIVE_SHADOWS]: { type: 'boolean', parser: Parameter.parseBoolean },
+      [Parameter.INTENSITY]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.DIRECTION]: { type: 'vector', parser: Parameter.parseVector },
+      [Parameter.ANGLE]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.EXPONENT]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.DIFFUSE]: { type: 'color', parser: Parameter.parseColor },
+      [Parameter.SPECULAR]: { type: 'color', parser: Parameter.parseColor },
+      [Parameter.ENVIRONMENT]: { type: 'string' },
+      [Parameter.ENVIRONMENT_COLOR]: { type: 'color', parser: Parameter.parseColor },
+      [Parameter.ENVIRONMENT_ROTATION]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.ENVIRONMENT_INTENSITY]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.ENVIRONMENT_BACKGROUND]: { type: 'string' },
+      [Parameter.ENVIRONMENT_USEDEFAULT]: { type: 'boolean', parser: Parameter.parseBoolean },
+    };
+  }
+
+  /**
+   * The default {@link ParameterValue}s returned as {@link ParameterBag} for a set of parameters in this class.
+   */
+  public static get defaultValues(): ParameterBag {
+    return {
+      [Parameter.SCALING]: '(1, 1, 1)',
+      [Parameter.POSITION]: '(0, 0, 0)',
+      [Parameter.ROTATION]: '(0, 0, 0)',
+    };
+  }
+
+  /**
+   * Gets the default {@link ParameterValue} for a given {@link Parameter} declared in this class.
+   */
+  public static getDefaultValue(parameter: string): ParameterValue {
+    return Parameter.defaultValues[parameter];
+  }
+
+  /**
+   * All parameters defined in this class.
+   */
+  public static get all() {
+    const all: string[] = [];
+    for (const parameter in Parameter) {
+      const property = Object.getOwnPropertyDescriptor(Parameter, parameter);
+      if (parameter.toUpperCase() === parameter && property && isString(property.value)) {
+        all.push(property.value);
+      }
+    }
+    return all;
+  }
+
+  /**
+   * Asserts whether given parameter is declared and valid.
+   */
+  public static assertParameter(parameterDeclaration: ParameterDeclarations, parameter: string, value: ParameterValue) {
+    if (!(parameter in parameterDeclaration)) {
+      // This is a valid case since we are not able to check parameters that are not declared.
+      // We just ignore parameters that are not declared.
+      return;
+    }
+    const declaration = parameterDeclaration[parameter];
+    const errorPrefix = `Invalid value for parameter "${parameter}" of type "${declaration.type}" given:`;
+    if (declaration.parser) {
+      try {
+        declaration.parser(value);
+      } catch (e: any) {
+        throw new ViewerError({
+          id: ViewerErrorIds.InvalidParameterValue,
+          message: `${errorPrefix}\n${e.message}.\nGiven value: ${value}`,
+        });
+      }
+    }
+    switch (declaration.type) {
+      case 'select':
+        if (!declaration.options) {
+          throw new ViewerError({
+            id: ViewerErrorIds.UnknownParameterOption,
+            message: `No options defined for parameter declaration "${parameter}" of type "${declaration.type}".`,
+          });
+        }
+        if (declaration.options.indexOf(value) === -1) {
+          throw Error(
+            `${errorPrefix}\nValid values are: "${declaration.options.join('", "')}".\nGiven value: ${value}`
+          );
+        }
+        break;
+    }
+  }
+
+  /**
+   * Parses given {@link ParameterBag} with given {@link ParameterDeclarations}.
+   */
+  public static parseFromDeclarations(
+    declarations: ParameterDeclarations,
+    parameterBag: ParameterBag
+  ): ParsedParameterBag {
+    const parameters: ParsedParameterBag = {};
+    for (const parameter in parameterBag) {
+      const value = get(parameterBag, parameter);
+      parameters[parameter] = value;
+      const declaration: ParameterDeclaration = declarations[parameter];
+      if (declaration) {
+        if (!isEmpty(value) && declaration.parser) {
+          parameters[parameter] = declaration.parser(value);
+        }
+      }
+    }
+    return parameters;
+  }
+
+  /**
+   * Parses a string of format `'(x,y,z)'` to a `Vector3`.
+   */
+  public static parseVector(value: ParameterValue): Vector3 {
+    if (!isString(value)) {
+      throw new Error(`Unable to convert "${value}" into a Vector: not a string.`);
+    }
+    let cleanedValue = value.split(' ').join('');
+    if (cleanedValue.startsWith('(') && cleanedValue.endsWith(')')) {
+      cleanedValue = cleanedValue.substring(1, cleanedValue.length - 1);
+      const [x, y, z] = cleanedValue.split(',').map(value => parseFloat(value));
+      return new Vector3(x, y, z);
+    } else {
+      throw new Error(`Unable to parse "${value}" to a Vector: expected "(x,y,z)".`);
+    }
+  }
+
+  /**
+   * Stringifies a Vector3 to format `(x,y,z)`.
+   */
+  public static stringifyVector(value: Vector3): string {
+    return `(${value.x},${value.y},${value.z})`;
+  }
+
+  /**
+   * Parses a string of format `'(x,y,z)'` with angular degrees to a `Vector3` with rotation information in radians.
+   */
+  public static parseRotation(value: ParameterValue): Vector3 {
+    const rotation = Parameter.parseVector(value);
+    const deg2rad = function (deg: number) {
+      return (deg * Math.PI) / 180;
+    };
+    return rotation.set(deg2rad(rotation.x), deg2rad(rotation.y), deg2rad(rotation.z));
+  }
+
+  /**
+   * Parses a string of format `'(x,y,z)'` or a simple `number` to a `Vector3` for scaling.
+   */
+  public static parseScaling(value: ParameterValue): Vector3 {
+    let scaling = new Vector3();
+    if (isString(value)) {
+      const cleanedFactor = value.split(' ').join('');
+      if (cleanedFactor.startsWith('(') && cleanedFactor.endsWith(')')) {
+        scaling = Parameter.parseVector(cleanedFactor);
+      } else {
+        const _factor = parseFloat(value);
+        scaling = new Vector3(_factor, _factor, _factor);
+      }
+    } else if (isNumber(value)) {
+      scaling = new Vector3(value, value, value);
+    } else {
+      throw new Error(`Unable to convert "${value}" to a Vector: expected "(x,y,z)".`);
+    }
+    return scaling;
+  }
+
+  /**
+   * Parses a string of format `'#rrggbb'` or `'(r,g,b)'` to a `Color3`.
+   */
+  public static parseColor(value: ParameterValue): Color3 {
+    const cleanedValue = value.toString().split(' ').join('');
+    if (cleanedValue.startsWith('#')) {
+      return Color3.FromHexString(value.toString());
+    }
+    if (cleanedValue.startsWith('(') && cleanedValue.endsWith(')')) {
+      const rgb = cleanedValue.substring(1, cleanedValue.length - 1);
+      const [r, g, b] = rgb.split(',').map(value => parseFloat(value));
+      return Color3.FromInts(r, g, b);
+    }
+    const humanReadable = capitalize(cleanedValue);
+    // disable lint for this rule as there is no smoother option for checking static class functions (eg Color.Red())
+    // eslint-disable-next-line no-prototype-builtins
+    if (Color3.hasOwnProperty(humanReadable)) {
+      // @ts-ignore same as above
+      return Color3[humanReadable]();
+    }
+    throw new Error(
+      `Unable to parse "${value}" to a Color: expected "#rrggbb", "(r,g,b)" or any human readable property implemented in Color3.`
+    );
+  }
+
+  /**
+   * Parses a `boolean` string (`'true'`/`'1'` or `'false'`/`'0'`) or `number` (`1` or `0`) to a `boolean` or
+   * `undefined`.
+   */
+  public static parseBoolean(value: ParameterValue): boolean {
+    if (value.toString() === 'true' || value.toString() === '1') {
+      return true;
+    } else if (value.toString() === 'false' || value.toString() === '0') {
+      return false;
+    }
+    throw new Error(`Unable to parse "${value}" to a boolean.`);
+  }
+
+  /**
+   * Parses a number `string` to a `number`.
+   */
+  public static parseNumber(value: ParameterValue): number {
+    return parseFloat(value.toString());
+  }
+
+  /**
+   * Parses string defintion of a paintable into a paintable object.\
+   * Here are some examples:
+   * ```ts
+   * // Default definition as JSON object:
+   * '{ "src": "https://path.to/image.jpg", "uScale": 0.5 }'
+   *
+   * // Short hand definition, only contains source string:
+   * 'https://path.to/image.jpg'
+   *
+   * // Full content, paintable texture is flipped in both directions
+   * '{ "src": "https://path.to/image.jpg", "uScale": -1, "vScale": -1, "uOffset": 0, "vOffset": 0 }'
+   *
+   * // SVG content can be used directly:
+   * '<svg>...</svg>'
+   *
+   * // SVG in src property works as well:
+   * '{ "src": "<svg>...</svg>", "uScale": 0.5 }'
+   * ```
+   */
+  public static parsePaintable(value: ParameterValue): PaintableValue {
+    if (!isString(value)) {
+      throw new Error(`Not a string.`);
+    }
+
+    const paintableValue: PaintableValue = { src: '' };
+    let valObj: { [key: string]: any } | null = null;
+
+    try {
+      valObj = JSON.parse(value);
+    } catch {
+      // use string directly
+      paintableValue.src = value;
+
+      if (value.startsWith('{')) {
+        // seems like the user tried to use a JSON string, as the input starts with {
+        throw new Error(`Not a valid JSON string.`);
+      }
+    }
+
+    if (valObj) {
+      // input string is JSON, src attribute is required
+      if (!valObj.src) {
+        throw new Error(`Property "src" is missing.`);
+      }
+
+      if (!isString(valObj.src)) {
+        throw new Error(`Property "src" is not a string.`);
+      }
+
+      // split src and options
+      const { src, ...options } = valObj;
+      paintableValue.src = src;
+
+      // only forward valid paintable options
+      const validOptionKeys = ['uScale', 'vScale', 'uOffset', 'vOffset'];
+      const { validOptions, invalidKeys } = Object.entries(options).reduce(
+        (accRes, [curKey, curValue]) => {
+          const isValidKey = validOptionKeys.includes(curKey);
+          if (isValidKey) {
+            accRes.validOptions[curKey] = curValue;
+          } else {
+            accRes.invalidKeys.push(curKey);
+          }
+
+          return accRes;
+        },
+        { validOptions: {} as { [key: string]: any }, invalidKeys: [] as string[] }
+      );
+
+      if (invalidKeys.length) {
+        console.warn('parsePaintable: invalid paintable options provided: ' + invalidKeys.toString());
+      }
+
+      paintableValue.options = validOptions;
+    }
+
+    return paintableValue;
+  }
+
+  /**
+   * Parses a string with comma separated values to a list of strings.
+   */
+  public static parseCommaSeparatedList(value: ParameterValue): string[] {
+    return value
+      .toString()
+      .split(',')
+      .map(s => s.trim());
+  }
+}