@combeenation/3d-viewer 9.0.0 → 9.0.2-alpha1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combeenation/3d-viewer",
-  "version": "9.0.0",
+  "version": "9.0.2-alpha1",
   "description": "Combeenation 3D Viewer",
   "homepage": "https://github.com/Combeenation/3d-viewer#readme",
   "bugs": {

package/src/api/classes/parameter.ts

@@ -160,11 +160,18 @@ export class Parameter {
   public static readonly METALLIC = 'metallic';
 
   /**
-   * Mutates the texture of a material, based on an svg string, image path or image data.
+   * 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';
 
@@ -276,7 +283,7 @@ export class Parameter {
    *
    * Usually the URL to an `*.env` file.
    *
-   * See [environment page](./../pages/Documentation/Environment.html) for details on how to use this.
+   * See [environment page](./../pages/documentation/Environment.html) for details on how to use this.
    *
    * Scopes:
    * * {@link SceneManager}
@@ -288,7 +295,7 @@ export class Parameter {
   /**
    * 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.
+   * See [environment page](./../pages/documentation/Environment.html) for details on how to use this.
    *
    * Scopes:
    * * {@link SceneManager}
@@ -301,7 +308,7 @@ export class Parameter {
    * 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.
+   * See [environment page](./../pages/documentation/Environment.html) for details on how to use this.
    *
    * Scopes:
    * * {@link SceneManager}
@@ -313,7 +320,7 @@ export class Parameter {
   /**
    * Intensity of IBL. Defaults to 1, usually between 0 & 2.
    *
-   * See [environment page](./../pages/Documentation/Environment.html) for details on how to use this.
+   * See [environment page](./../pages/documentation/Environment.html) for details on how to use this.
    *
    * Scopes:
    * * {@link SceneManager}
@@ -329,7 +336,7 @@ export class Parameter {
    * 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.
+   * See [environment page](./../pages/documentation/Environment.html) for details on how to use this.
    *
    * Scopes:
    * * {@link SceneManager}
@@ -347,7 +354,7 @@ export class Parameter {
    *
    * 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.
+   * See [environment page](./../pages/documentation/Environment.html) for details on how to use this.
    *
    * Scopes:
    * * {@link SceneManager}
@@ -372,6 +379,10 @@ export class Parameter {
       [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 },
@@ -402,13 +413,6 @@ export class Parameter {
     };
   }
 
-  /**
-   * 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.
    */
@@ -440,14 +444,14 @@ export class Parameter {
       return;
     }
     const declaration = parameterDeclaration[parameter];
-    const genericError = `"${value}" is not a valid value for parameter "${parameter}" of type "${declaration.type}".`;
+    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: `${genericError} ${e.message}`,
+          message: `${errorPrefix}\n${e.message}.\nGiven value: ${value}`,
         });
       }
     }
@@ -460,7 +464,9 @@ export class Parameter {
           });
         }
         if (declaration.options.indexOf(value) === -1) {
-          throw Error(genericError + ` Valid values are: "${declaration.options.join('", "')}".`);
+          throw Error(
+            `${errorPrefix}\nValid values are: "${declaration.options.join('", "')}".\nGiven value: ${value}`
+          );
         }
         break;
     }
@@ -589,18 +595,28 @@ export class Parameter {
   }
 
   /**
-   * Parses string defintion of a paintable into a paintable object.
+   * 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 {
+   * ```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(`Unable to parse "${value}" to a PaintableValue: not a string.`);
+      throw new Error(`Not a string.`);
     }
 
     const paintableValue: PaintableValue = { src: '' };
@@ -614,18 +630,18 @@ export class Parameter {
 
       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.`);
+        throw new Error(`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.`);
+        throw new Error(`Property "src" is missing.`);
       }
 
       if (!isString(valObj.src)) {
-        throw new Error(`Unable to parse "${value}" to a PaintableValue: property "src" is not a string.`);
+        throw new Error(`Property "src" is not a string.`);
       }
 
       // split src and options
@@ -649,7 +665,7 @@ export class Parameter {
       );
 
       if (invalidKeys.length) {
-        console.warn('parsePaintableValue: invalid paintable options provided: ' + invalidKeys.toString());
+        console.warn('parsePaintable: invalid paintable options provided: ' + invalidKeys.toString());
       }
 
       paintableValue.options = validOptions;

package/src/api/manager/tagManager.ts

@@ -2,6 +2,7 @@ import { Event, emitter } from '../classes/event';
 import { FuzzyMap } from '../classes/fuzzyMap';
 import { Parameter } from '../classes/parameter';
 import { Viewer } from '../classes/viewer';
+import { ViewerError, ViewerErrorIds } from '../classes/viewerError';
 import {
   assertMeshCapability,
   drawPaintableOnMaterial,
@@ -427,7 +428,7 @@ export class TagManager {
       return true;
     });
     this.parameterObservers.set(Parameter.PAINTABLE, async payload => {
-      const paintableValue: PaintableValue = Parameter.parsePaintableValue(payload.newValue);
+      const paintableValue: PaintableValue = Parameter.parsePaintable(payload.newValue);
 
       // check if value is svg or image source, do the conversion accordingly
       const srcIsSvg = isSvg(paintableValue.src);
@@ -437,9 +438,20 @@ export class TagManager {
         throw new Error(`Setting paintable value failed: "${paintableValue.src}" is no valid SVG string.`);
       }
 
-      const imageSource: CanvasImageSource = srcIsSvg
-        ? await createImageFromSvg(paintableValue.src)
-        : await createImageFromImgSrc(paintableValue.src);
+      let imageSource: CanvasImageSource;
+      try {
+        imageSource = srcIsSvg
+          ? await createImageFromSvg(paintableValue.src)
+          : await createImageFromImgSrc(paintableValue.src);
+      } catch {
+        // SVG might be invalid, even if it passes `isSvg` check
+        // in this case the image can't be created and will throw an error, which should be handled by the viewer and
+        // Combeenation viewer control
+        throw new ViewerError({
+          id: ViewerErrorIds.InvalidParameterValue,
+          message: `Invalid value for parameter "paintable" given:\nImage can't be created from source string.\nGiven value: ${paintableValue.src}`,
+        });
+      }
 
       // apply image source on desired material(s)
       for (const material of payload.materials) {

package/src/api/util/babylonHelper.ts

@@ -37,6 +37,10 @@ const backgroundDomeName = 'BackgroundDome_ViewerGenerated';
 const envHelperMetadataName = 'viewerEnvHelper';
 const materialWaitingToBeSetMetadataName = 'materialWaitingToBeSet';
 
+// Holds pending `createMaterialFromCbnAssets` promises for dedicated material ids
+// In this case we can make sure that a single material is not requested multiple times if used in various nodes
+const getMaterialPromises: Map<string, Promise<Material | null>> = new Map();
+
 /**
  * @param node
  * @return Node
@@ -435,15 +439,54 @@ const setMaterial = function (node: TransformNode, materialId: string, deep: boo
   }
 };
 
+/**
+ * Removes material from promise map once it has been added to the scene, because we can be sure that the material will
+ * be taken from the scene directly, the next time it is requested
+ */
+const onNewMaterialAddedCb = (material: Material) => {
+  if (getMaterialPromises.has(material.id)) {
+    getMaterialPromises.delete(material.id);
+  }
+};
+
+/**
+ * Responsible for adding the `onNewMaterialAddedCb` only once
+ */
+const registerOnNewMaterialAddedCbOnce = (scene: Scene) => {
+  const observerAlreadyAssigned = scene.onNewMaterialAddedObservable.observers.find(
+    observer => observer.callback === onNewMaterialAddedCb
+  );
+
+  if (!observerAlreadyAssigned) {
+    scene.onNewMaterialAddedObservable.add(onNewMaterialAddedCb);
+  }
+};
+
 /**
  * Gets the Material either from the given {@link Variant}, the given scene or tries to create it from an Combeenation
  * material asset when inside a Combeenation configurator.
  */
 const getOrCreateMaterial = async function (scene: Scene, materialId: string, variant?: Variant): Promise<Material> {
+  registerOnNewMaterialAddedCbOnce(scene);
+
   let chosenMaterial: Material | undefined | null;
   chosenMaterial = variant?.inheritedMaterials.find(mat => mat.id === materialId);
   chosenMaterial = chosenMaterial || scene.materials.find(mat => mat.id === materialId);
-  chosenMaterial = chosenMaterial || (await createMaterialFromCbnAssets(materialId, scene));
+
+  if (!chosenMaterial) {
+    // material not available yet, request it from Combeenation assets
+    if (getMaterialPromises.has(materialId)) {
+      // request is already pending, just wait for the result
+      chosenMaterial = await getMaterialPromises.get(materialId);
+    } else {
+      // request not pending, call the dedicated function
+      const getMaterialProm = createMaterialFromCbnAssets(materialId, scene);
+      // store the promise in a global map, so that subsequent requests can reference it
+      getMaterialPromises.set(materialId, getMaterialProm);
+      chosenMaterial = await getMaterialProm;
+    }
+  }
+
   if (chosenMaterial) {
     return chosenMaterial as Material;
   }

package/src/api/util/globalTypes.ts

@@ -394,7 +394,7 @@ type ParameterDeclarations = {
 };
 
 type ParameterDeclaration = {
-  type: 'string' | 'boolean' | 'number' | 'color' | 'select' | 'vector' | 'csl';
+  type: 'string' | 'boolean' | 'number' | 'color' | 'select' | 'vector' | 'csl' | 'paintable';
   parser?: any;
   options?: ParameterValue[];
 };

package/src/api/util/resourceHelper.ts

@@ -131,10 +131,13 @@ const createImageFromSvg = async function (svgSrc: string): Promise<HTMLImageEle
 const createImageFromImgSrc = async function (imgSrc: string): Promise<HTMLImageElement> {
   const img = new Image();
 
-  await new Promise(resolve => {
+  await new Promise((resolve, reject) => {
     img.onload = () => {
       setTimeout(resolve, 0);
     };
+    img.onerror = () => {
+      reject();
+    };
     img.crossOrigin = 'anonymous';
     img.src = imgSrc;
   });

package/src/dev.ts

@@ -25,7 +25,7 @@ window.Cbn = {
   Assets: {
     async getMaterial(materialId: string) {
       //! this creates a new function on the object that uses the imported function of the same name..
-      const material = getMaterial(materialId);
+      const material = await getMaterial(materialId);
       if (material) return material;
 
       // Fallback to random mock material