@combeenation/3d-viewer 14.0.1-rc1 → 15.0.0

package/src/internal/paintable-helper.ts

@@ -1,310 +1,258 @@
-import {
-  DynamicTexture,
-  Material,
-  PBRMaterial,
-  ParameterValue,
-  Scene,
-  StandardMaterial,
-  Texture,
-  ViewerError,
-  ViewerErrorIds,
-} from '../index';
-import isSvg from 'is-svg';
-import { isString } from 'lodash-es';
-
-type PaintableValue = {
-  src: string;
-  options?: PaintableOptions;
-};
-
-type PaintableOptions = {
-  uScale?: number;
-  uOffset?: number;
-  vScale?: number;
-  vOffset?: number;
-};
-
-/**
- * Observer implementation for "paintable" parameter.
- * Basically creates a dynamic texture from the source image and assigns it as albedo (or diffuse) texture.
- */
-export async function paintableParameterObserver(
-  newValue: ParameterValue,
-  materials: Material[],
-  scene: Scene
-): Promise<void> {
-  const paintable = parsePaintable(newValue);
-
-  // check if value is svg or image source, do the conversion accordingly
-  const srcIsSvg = isSvg(paintable.src);
-  if (!srcIsSvg && paintable.src.includes('<svg') && paintable.src.includes('</svg>')) {
-    // seems like the user tried to use a SVG string, as <svg> tags are used
-    // inform the user that this is not a valid SVG string
-    throw new ViewerError({
-      id: ViewerErrorIds.InvalidParameterValue,
-      message: `Invalid value for parameter "paintable" given:\nsource string is no valid SVG string\nGiven value: ${paintable.src}`,
-    });
-  }
-
-  let imageSource: CanvasImageSource;
-  try {
-    imageSource = srcIsSvg ? await _createImageFromSvg(paintable.src) : await _createImageFromImgSrc(paintable.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: ${paintable.src}`,
-    });
-  }
-
-  // apply image source on desired material(s)
-  for (const material of materials) {
-    _drawPaintableOnMaterial(material, imageSource, scene, paintable.options);
-  }
-}
-
-/**
- * Parser for paintable value.
- * ATM this is only used internally, but it could theoretically be used to create ones own paintable implementation.
- *
- * @param value The value to parse. 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 }'
- *              ```
- */
-export function parsePaintable(value: ParameterValue): PaintableValue {
-  if (!isString(value)) {
-    throw new ViewerError({
-      id: ViewerErrorIds.InvalidParameterValue,
-      message: `Unable to parse paintable value: not a string\nGiven value: ${value}`,
-    });
-  }
-
-  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 ViewerError({
-        id: ViewerErrorIds.InvalidParameterValue,
-        message: `Unable to parse paintable value: not a valid JSON string\nGiven value: ${value}`,
-      });
-    }
-  }
-
-  if (valObj) {
-    // input string is JSON, src attribute is required
-    if (!valObj.src) {
-      throw new ViewerError({
-        id: ViewerErrorIds.InvalidParameterValue,
-        message: `Unable to parse paintable value: property "src" is missing\nGiven value: ${value}`,
-      });
-    }
-
-    if (!isString(valObj.src)) {
-      throw new ViewerError({
-        id: ViewerErrorIds.InvalidParameterValue,
-        message: `Unable to parse paintable value: property "src" is not a string\nGiven value: ${value}`,
-      });
-    }
-
-    // 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('Invalid paintable options provided: ' + invalidKeys.toString());
-    }
-
-    paintableValue.options = validOptions;
-  }
-
-  return paintableValue;
-}
-
-function _drawPaintableOnMaterial(
-  material: Material,
-  imageSource: HTMLImageElement,
-  scene: Scene,
-  options?: PaintableOptions
-): void {
-  // always take width and height from image source, scaling is done with uvScale properties
-  const widthAndHeight = {
-    width: imageSource.width,
-    height: imageSource.height,
-  };
-
-  const texture = new DynamicTexture(`${material.id}.paintable_texture`, widthAndHeight, scene);
-
-  // draw image on texture
-  const ctx = texture.getContext();
-  ctx.drawImage(imageSource, 0, 0);
-  texture.update();
-
-  // apply settings from paintable options to tweak position and scaling of image on the texture
-  texture.uScale = options?.uScale ?? texture.uScale;
-  texture.vScale = options?.vScale ?? texture.vScale;
-  texture.uOffset = options?.uOffset ?? texture.uOffset;
-  texture.vOffset = options?.vOffset ?? texture.vOffset;
-
-  // wrap mode is preferred, as it will always show the texture, no matter which position offset is currently chosen
-  // clamp mode requires more knowledge (and patience) when adjusting the uv scale and offset values
-  texture.wrapU = Texture.WRAP_ADDRESSMODE;
-  texture.wrapV = Texture.WRAP_ADDRESSMODE;
-
-  // apply the paintable texture on the dedicated material type
-  const materialCls = material.getClassName();
-  switch (materialCls) {
-    case 'PBRMaterial':
-      (material as PBRMaterial).albedoTexture = texture;
-      break;
-    case 'StandardMaterial':
-      (material as StandardMaterial).diffuseTexture = texture;
-      break;
-    default:
-      throw new Error(`Setting paintable texture for material of instance "${materialCls}" not implemented (yet)`);
-  }
-}
-
-/**
- * Creates a HTML image element based on a SVG string, whereas all the embedded assets in the SVG (eg: fonts, images)
- * are already loaded and exchanged by their base64 representation.\
- * There the output image can exist as "standalone" image and may be used for example as a paintable.
- *
- * !!CAUTION!!: The used functions within this code section are very well evaluated since most alternatives
- * somehow don't work in Safari, as mentioned in the following BJS forum entries:
- * - https://forum.babylonjs.com/t/drawing-svg-content-text-into-dynamictexture-doesnt-work-in-safari-v15/25048
- * - https://forum.babylonjs.com/t/texture-createfrombase64string-doesnt-seem-to-work-for-ios-devices-initially/25502
- */
-async function _createImageFromSvg(svgSrc: string): Promise<HTMLImageElement> {
-  // replace assets with their base64 versions in svg source code
-  const svgWithAssetsEmbedded = await _embedAssets(svgSrc);
-
-  // create data string which can be used as an image source
-  const svgEncoded = 'data:image/svg+xml,' + encodeURIComponent(svgWithAssetsEmbedded);
-
-  return _createImageFromImgSrc(svgEncoded);
-}
-
-/**
- * Creates an HTML image element from a dedicated image source.\
- * Also waits until the image has loaded.
- *
- * !!CAUTION!!: The `setTimeout` after loading is finished is required due to a Safari bug:
- * - https://bugs.webkit.org/show_bug.cgi?id=39059
- * - https://bugs.webkit.org/show_bug.cgi?id=219770
- *
- * It's not 100% ensured that the timeout solves the issue in every case, but there is no other way unfortunately.\
- * => Keep an eye on it in future projects
- *
- * @param imgSrc Theoretically every source is valid which is also supported by
- *               [HTMLImageElement.src](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/src).\
- *               Known exceptions are SVGs with embedded assets that are provided as object URL. See comments in
- *               {@link createImageFromSvg} for further details.
- */
-async function _createImageFromImgSrc(imgSrc: string): Promise<HTMLImageElement> {
-  const img = new Image();
-
-  await new Promise((resolve, reject) => {
-    img.onload = (): void => {
-      setTimeout(resolve, 0);
-    };
-    img.onerror = (): void => {
-      reject();
-    };
-    img.crossOrigin = 'anonymous';
-    img.src = imgSrc;
-  });
-
-  return img;
-}
-
-/**
- * Replaces all supported image & font URLs in the given SVG with their base64 representation.
- */
-async function _embedAssets(svgSrc: string): Promise<string> {
-  const _imageExtensions = ['png', 'gif', 'jpg', 'jpeg', 'svg', 'bmp'];
-  const _fontExtensions = ['woff2', 'woff', 'ttf', 'otf'];
-  const _assetExtensions = [..._imageExtensions, ..._fontExtensions];
-  // Regex copied from https://stackoverflow.com/a/8943487/1273551, not "stress tested"...
-  const urlRegex = /(\bhttps?:\/\/[-A-Z0-9+&@#/%?=~_|!:,.;]*[-A-Z0-9+&@#/%=~_|])/gi;
-  const allUrls = svgSrc.match(urlRegex) as string[];
-
-  const assetUrls = allUrls.filter(url => {
-    const indexParam = url.indexOf('?');
-    // remove url parameter to recognize extension
-    if (indexParam > -1) {
-      url = url.substring(0, indexParam);
-    }
-    return _assetExtensions.some(extension => url.toLowerCase().endsWith(`.${extension}`));
-  });
-  const assetBase64Fetcher = assetUrls.map(_fetchBase64AssetUrl);
-  const assetFetcherResults = await Promise.all(assetBase64Fetcher);
-  return assetFetcherResults.reduce((svgSrc, x) => svgSrc.replace(x.url, x.base64), svgSrc);
-}
-
-/**
- * Fetch asset (image or font) and convert it to base64 string representation.
- */
-async function _fetchBase64AssetUrl(assetUrl: string): Promise<{ url: string; base64: string }> {
-  // TODO WTT: Cache known base64 representation and only fetch/convert when not already known.
-  //           Usually the fetch shouldn't hit the network but the browser cache since the SVG was already drawn..
-  const resp = await fetch(assetUrl);
-  const blob = await resp.blob();
-
-  return new Promise((resolve, reject) => {
-    const reader = new FileReader();
-    reader.onloadend = (event): void => {
-      const target = event.target;
-      if (!target) {
-        return reject(`Asset with URL "${assetUrl}" could not be loaded.`);
-      }
-      const result = target.result;
-      if (!result) {
-        return reject(`Asset with URL "${assetUrl}" returned an empty result.`);
-      }
-      resolve({
-        url: assetUrl,
-        base64: result.toString() as string,
-      });
-    };
-    reader.readAsDataURL(blob);
-  });
-}
+import {
+  DynamicTexture,
+  Material,
+  PBRMaterial,
+  ParameterValue,
+  Scene,
+  StandardMaterial,
+  Texture,
+  ViewerError,
+  ViewerErrorIds,
+} from '../index';
+import { embedAssets } from './svg-helper';
+import isSvg from 'is-svg';
+import { isString } from 'lodash-es';
+
+type PaintableValue = {
+  src: string;
+  options?: PaintableOptions;
+};
+
+type PaintableOptions = {
+  uScale?: number;
+  uOffset?: number;
+  vScale?: number;
+  vOffset?: number;
+};
+
+/**
+ * Observer implementation for "paintable" parameter.
+ * Basically creates a dynamic texture from the source image and assigns it as albedo (or diffuse) texture.
+ */
+export async function paintableParameterObserver(
+  newValue: ParameterValue,
+  materials: Material[],
+  scene: Scene
+): Promise<void> {
+  const paintable = parsePaintable(newValue);
+
+  // check if value is svg or image source, do the conversion accordingly
+  const srcIsSvg = isSvg(paintable.src);
+  if (!srcIsSvg && paintable.src.includes('<svg') && paintable.src.includes('</svg>')) {
+    // seems like the user tried to use a SVG string, as <svg> tags are used
+    // inform the user that this is not a valid SVG string
+    throw new ViewerError({
+      id: ViewerErrorIds.InvalidParameterValue,
+      message: `Invalid value for parameter "paintable" given:\nsource string is no valid SVG string\nGiven value: ${paintable.src}`,
+    });
+  }
+
+  let imageSource: CanvasImageSource;
+  try {
+    imageSource = srcIsSvg ? await _createImageFromSvg(paintable.src) : await _createImageFromImgSrc(paintable.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: ${paintable.src}`,
+    });
+  }
+
+  // apply image source on desired material(s)
+  for (const material of materials) {
+    _drawPaintableOnMaterial(material, imageSource, scene, paintable.options);
+  }
+}
+
+/**
+ * Parser for paintable value.
+ * ATM this is only used internally, but it could theoretically be used to create ones own paintable implementation.
+ *
+ * @param value The value to parse. 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 }'
+ *              ```
+ */
+export function parsePaintable(value: ParameterValue): PaintableValue {
+  if (!isString(value)) {
+    throw new ViewerError({
+      id: ViewerErrorIds.InvalidParameterValue,
+      message: `Unable to parse paintable value: not a string\nGiven value: ${value}`,
+    });
+  }
+
+  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 ViewerError({
+        id: ViewerErrorIds.InvalidParameterValue,
+        message: `Unable to parse paintable value: not a valid JSON string\nGiven value: ${value}`,
+      });
+    }
+  }
+
+  if (valObj) {
+    // input string is JSON, src attribute is required
+    if (!valObj.src) {
+      throw new ViewerError({
+        id: ViewerErrorIds.InvalidParameterValue,
+        message: `Unable to parse paintable value: property "src" is missing\nGiven value: ${value}`,
+      });
+    }
+
+    if (!isString(valObj.src)) {
+      throw new ViewerError({
+        id: ViewerErrorIds.InvalidParameterValue,
+        message: `Unable to parse paintable value: property "src" is not a string\nGiven value: ${value}`,
+      });
+    }
+
+    // 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('Invalid paintable options provided: ' + invalidKeys.toString());
+    }
+
+    paintableValue.options = validOptions;
+  }
+
+  return paintableValue;
+}
+
+function _drawPaintableOnMaterial(
+  material: Material,
+  imageSource: HTMLImageElement,
+  scene: Scene,
+  options?: PaintableOptions
+): void {
+  // always take width and height from image source, scaling is done with uvScale properties
+  const widthAndHeight = {
+    width: imageSource.width,
+    height: imageSource.height,
+  };
+
+  const texture = new DynamicTexture(`${material.id}.paintable_texture`, widthAndHeight, scene);
+
+  // draw image on texture
+  const ctx = texture.getContext();
+  ctx.drawImage(imageSource, 0, 0);
+  texture.update();
+
+  // apply settings from paintable options to tweak position and scaling of image on the texture
+  texture.uScale = options?.uScale ?? texture.uScale;
+  texture.vScale = options?.vScale ?? texture.vScale;
+  texture.uOffset = options?.uOffset ?? texture.uOffset;
+  texture.vOffset = options?.vOffset ?? texture.vOffset;
+
+  // wrap mode is preferred, as it will always show the texture, no matter which position offset is currently chosen
+  // clamp mode requires more knowledge (and patience) when adjusting the uv scale and offset values
+  texture.wrapU = Texture.WRAP_ADDRESSMODE;
+  texture.wrapV = Texture.WRAP_ADDRESSMODE;
+
+  // apply the paintable texture on the dedicated material type
+  const materialCls = material.getClassName();
+  switch (materialCls) {
+    case 'PBRMaterial':
+      (material as PBRMaterial).albedoTexture = texture;
+      break;
+    case 'StandardMaterial':
+      (material as StandardMaterial).diffuseTexture = texture;
+      break;
+    default:
+      throw new Error(`Setting paintable texture for material of instance "${materialCls}" not implemented (yet)`);
+  }
+}
+
+/**
+ * Creates a HTML image element based on a SVG string, whereas all the embedded assets in the SVG (eg: fonts, images)
+ * are already loaded and exchanged by their base64 representation.\
+ * There the output image can exist as "standalone" image and may be used for example as a paintable.
+ *
+ * !!CAUTION!!: The used functions within this code section are very well evaluated since most alternatives
+ * somehow don't work in Safari, as mentioned in the following BJS forum entries:
+ * - https://forum.babylonjs.com/t/drawing-svg-content-text-into-dynamictexture-doesnt-work-in-safari-v15/25048
+ * - https://forum.babylonjs.com/t/texture-createfrombase64string-doesnt-seem-to-work-for-ios-devices-initially/25502
+ */
+async function _createImageFromSvg(svgSrc: string): Promise<HTMLImageElement> {
+  // replace assets with their base64 versions in svg source code
+  const svgWithAssetsEmbedded = await embedAssets(svgSrc);
+
+  // create data string which can be used as an image source
+  const svgEncoded = 'data:image/svg+xml,' + encodeURIComponent(svgWithAssetsEmbedded);
+
+  return _createImageFromImgSrc(svgEncoded);
+}
+
+/**
+ * Creates an HTML image element from a dedicated image source.\
+ * Also waits until the image has loaded.
+ *
+ * !!CAUTION!!: The `setTimeout` after loading is finished is required due to a Safari bug:
+ * - https://bugs.webkit.org/show_bug.cgi?id=39059
+ * - https://bugs.webkit.org/show_bug.cgi?id=219770
+ *
+ * It's not 100% ensured that the timeout solves the issue in every case, but there is no other way unfortunately.\
+ * => Keep an eye on it in future projects
+ *
+ * @param imgSrc Theoretically every source is valid which is also supported by
+ *               [HTMLImageElement.src](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/src).\
+ *               Known exceptions are SVGs with embedded assets that are provided as object URL. See comments in
+ *               {@link createImageFromSvg} for further details.
+ */
+async function _createImageFromImgSrc(imgSrc: string): Promise<HTMLImageElement> {
+  const img = new Image();
+
+  await new Promise((resolve, reject) => {
+    img.onload = (): void => {
+      setTimeout(resolve, 0);
+    };
+    img.onerror = (): void => {
+      reject();
+    };
+    img.crossOrigin = 'anonymous';
+    img.src = imgSrc;
+  });
+
+  return img;
+}

package/src/internal/svg-helper.ts

@@ -0,0 +1,52 @@
+/**
+ * Replaces all supported image & font URLs in the given SVG with their base64 representation.
+ */
+export async function embedAssets(svgSrc: string): Promise<string> {
+  const _imageExtensions = ['png', 'gif', 'jpg', 'jpeg', 'svg', 'bmp'];
+  const _fontExtensions = ['woff2', 'woff', 'ttf', 'otf'];
+  const _assetExtensions = [..._imageExtensions, ..._fontExtensions];
+  // Regex copied from https://stackoverflow.com/a/8943487/1273551, not "stress tested"...
+  const urlRegex = /(\bhttps?:\/\/[-A-Z0-9+&@#/%?=~_|!:,.;]*[-A-Z0-9+&@#/%=~_|])/gi;
+  const allUrls = svgSrc.match(urlRegex) as string[];
+
+  const assetUrls = allUrls.filter(url => {
+    const indexParam = url.indexOf('?');
+    // remove url parameter to recognize extension
+    if (indexParam > -1) {
+      url = url.substring(0, indexParam);
+    }
+    return _assetExtensions.some(extension => url.toLowerCase().endsWith(`.${extension}`));
+  });
+  const assetBase64Fetcher = assetUrls.map(_fetchBase64AssetUrl);
+  const assetFetcherResults = await Promise.all(assetBase64Fetcher);
+  return assetFetcherResults.reduce((svgSrc, x) => svgSrc.replace(x.url, x.base64), svgSrc);
+}
+
+/**
+ * Fetch asset (image or font) and convert it to base64 string representation.
+ */
+async function _fetchBase64AssetUrl(assetUrl: string): Promise<{ url: string; base64: string }> {
+  // TODO WTT: Cache known base64 representation and only fetch/convert when not already known.
+  //           Usually the fetch shouldn't hit the network but the browser cache since the SVG was already drawn..
+  const resp = await fetch(assetUrl);
+  const blob = await resp.blob();
+
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = (event): void => {
+      const target = event.target;
+      if (!target) {
+        return reject(`Asset with URL "${assetUrl}" could not be loaded.`);
+      }
+      const result = target.result;
+      if (!result) {
+        return reject(`Asset with URL "${assetUrl}" returned an empty result.`);
+      }
+      resolve({
+        url: assetUrl,
+        base64: result.toString() as string,
+      });
+    };
+    reader.readAsDataURL(blob);
+  });
+}