@combeenation/3d-viewer 14.1.0 → 15.1.0-beta1

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);
+  });
+}

package/src/internal/tags-helper.ts

@@ -19,18 +19,13 @@ export function getTags(object: TagTarget): string[] {
 }
 
 export function setTags(object: TagTarget, tags: string[]): void {
+  deleteAllTags(object);
   const tagsString = tags.join(' ');
   Tags.AddTagsTo(object, tagsString);
 }
 
-export function deleteAllTags(object: TagTarget): void {
-  const curTags = Tags.GetTags(object);
-  if (curTags) {
-    Tags.RemoveTagsFrom(object, curTags);
-  }
-}
-
 export function setTagsAsString(object: TagTarget, tagsString: string): void {
+  deleteAllTags(object);
   Tags.AddTagsTo(object, tagsString);
 }
 
@@ -39,3 +34,10 @@ export function cloneTags(sourceObject: TagTarget, destinationObject: TagTarget)
     Tags.AddTagsTo(destinationObject, Tags.GetTags(sourceObject, true));
   }
 }
+
+export function deleteAllTags(object: TagTarget): void {
+  const curTags = Tags.GetTags(object);
+  if (curTags) {
+    Tags.RemoveTagsFrom(object, curTags);
+  }
+}

package/src/internal/texture-parameter-helper.ts

@@ -0,0 +1,353 @@
+import { BaseTexture, Material, PBRMaterial, Scene, Texture, ViewerError, ViewerErrorIds } from '..';
+import { BuiltInParameter, ParameterManager } from '../manager/parameter-manager';
+import { embedAssets } from './svg-helper';
+import isSvg from 'is-svg';
+
+/**
+ * Texture parameters are a combination of the channel (e.g. albedo, bump, AO) and the "sub" parameter (e.g. uScale).
+ * Each parameter is available in each texture, that's why these textures parameter are defined as dotted path
+ * `albedoTexture.uScale`
+ * - channel: albedoTexture
+ * - parameter: uScale
+ * The consumer doesn't have to know this as there is `BuiltInParameters.createTextureParameter(channel, parameter)`,
+ * which composes this string internally
+ */
+
+export const BuiltInTextureParameter = {
+  image: 'image',
+  uOffset: 'uOffset',
+  vOffset: 'vOffset',
+  uScale: 'uScale',
+  vScale: 'vScale',
+  uAng: 'uAng',
+  vAng: 'vAng',
+  wAng: 'wAng',
+  clampU: 'clampU',
+  clampV: 'clampV',
+  uvSet: 'uvSet',
+};
+export type BuiltInTextureParameterKeys = keyof typeof BuiltInTextureParameter;
+
+export const ParameterTextureChannels = {
+  albedoTexture: 'albedoTexture',
+  metallicRoughnessTexture: 'metallicRoughnessTexture',
+  bumpTexture: 'bumpTexture',
+  emissiveTexture: 'emissiveTexture',
+  opacityTexture: 'opacityTexture',
+  ambientTexture: 'ambientTexture',
+  lightmapTexture: 'lightmapTexture',
+  detailmapTexture: 'detailmapTexture',
+};
+export type ParameterTextureChannelsKeys = keyof typeof ParameterTextureChannels;
+
+export function createBuiltInTextureParameter(parameterManager: ParameterManager, scene: Scene): void {
+  // create parameter observer for each channel
+  (Object.values(ParameterTextureChannels) as ParameterTextureChannelsKeys[]).forEach(channel => {
+    parameterManager.setParameterObserver(
+      `${channel}.${BuiltInTextureParameter.image}`,
+      async ({ newValue, materials }) => {
+        const image = ParameterManager.parseString(newValue);
+        let url = image;
+
+        const imageIsSvg = isSvg(image);
+        if (imageIsSvg) {
+          // NOTE: image can also be provided as "svg", which is more or less the successor of the "paintable"
+          // parameter. It misses the UV parameters, but we now have dedicated parameters for this.
+          // We used "Dynamic Textures" for paintables because we didn't know better I guess?
+          // However the rescaling functionality of "Dynamic Textures" is not required and therefore it can be
+          // implemented as a plain "Texture"
+          const svgWithAssetsEmbedded = await embedAssets(image);
+          // convert into a base64 string, as this can be directly interpreted as "url", at least for Babylon.js
+          url = 'data:image/svg+xml;base64,' + btoa(svgWithAssetsEmbedded);
+        } else if (image.includes('<svg') && image.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 "image" given:\nsource string is no valid SVG string\nGiven value: ${image}`,
+          });
+        }
+
+        for (const material of materials) {
+          const pbrMaterial = _assertAndConvertPBRMaterial(material, channel, BuiltInTextureParameter.image);
+          const texture = _getTextureFromParameterChannel(pbrMaterial, channel);
+
+          if (texture) {
+            // create a clone of the texture, in this way we can load the image before assigning it to the material
+            // channel
+            const clonedTexture = texture.clone();
+            // update texture and await loading time right away
+            await new Promise<void>(resolve => clonedTexture.updateURL(url, undefined, resolve));
+
+            _assignTextureParameterChannel(clonedTexture, pbrMaterial, channel);
+
+            // dispose old texture
+            texture.dispose();
+          } else {
+            // no texture, or wrong type => create texture from scratch
+            // first we check if some settings were provided in the material definition
+            const addMatSettings = await window.Cbn?.Assets.getMaterial(pbrMaterial.id);
+            const textureSettings = addMatSettings ? _getTextureObjFromParameterChannel(addMatSettings, channel) : {};
+
+            // overwrite the name with the url, as this is what the texture parser expects
+            (textureSettings as any).name = url;
+            // use parser instead of constructor to keep the original texture settings
+            const newTexture = Texture.Parse(textureSettings, scene, '') as Texture;
+
+            if (!newTexture) {
+              throw new ViewerError({
+                id: ViewerErrorIds.TextureCouldNotBeParsed,
+                message: `Texture with url "${url}" could not be parsed`,
+              });
+            }
+
+            // await loading of texture
+            await new Promise<void>(resolve => BaseTexture.WhenAllReady([newTexture], resolve));
+            _assignTextureParameterChannel(newTexture, pbrMaterial, channel);
+
+            // apply texture settings, which have been set before the texture creation
+            await parameterManager.applyTextureSettingsParameter(pbrMaterial, channel);
+          }
+        }
+      }
+    );
+    parameterManager.setParameterObserver(
+      `${channel}.${BuiltInTextureParameter.uOffset}`,
+      async ({ newValue, materials }) => {
+        const uOffset = ParameterManager.parseNumber(newValue);
+
+        for (const material of materials) {
+          const pbrMaterial = _assertAndConvertPBRMaterial(material, channel, BuiltInTextureParameter.uOffset);
+
+          _setUVTextureSetting('uOffset', uOffset, pbrMaterial, channel);
+        }
+      }
+    );
+    parameterManager.setParameterObserver(
+      `${channel}.${BuiltInTextureParameter.vOffset}`,
+      async ({ newValue, materials }) => {
+        const vOffset = ParameterManager.parseNumber(newValue);
+
+        for (const material of materials) {
+          const pbrMaterial = _assertAndConvertPBRMaterial(material, channel, BuiltInTextureParameter.vOffset);
+
+          _setUVTextureSetting('vOffset', vOffset, pbrMaterial, channel);
+        }
+      }
+    );
+    parameterManager.setParameterObserver(
+      `${channel}.${BuiltInTextureParameter.uScale}`,
+      async ({ newValue, materials }) => {
+        const uScale = ParameterManager.parseNumber(newValue);
+
+        for (const material of materials) {
+          const pbrMaterial = _assertAndConvertPBRMaterial(material, channel, BuiltInTextureParameter.uScale);
+
+          _setUVTextureSetting('uScale', uScale, pbrMaterial, channel);
+        }
+      }
+    );
+    parameterManager.setParameterObserver(
+      `${channel}.${BuiltInTextureParameter.vScale}`,
+      async ({ newValue, materials }) => {
+        const vScale = ParameterManager.parseNumber(newValue);
+
+        for (const material of materials) {
+          const pbrMaterial = _assertAndConvertPBRMaterial(material, channel, BuiltInTextureParameter.vScale);
+
+          _setUVTextureSetting('vScale', vScale, pbrMaterial, channel);
+        }
+      }
+    );
+    parameterManager.setParameterObserver(
+      `${channel}.${BuiltInTextureParameter.uAng}`,
+      async ({ newValue, materials }) => {
+        const uAng = ParameterManager.parseNumber(newValue);
+
+        for (const material of materials) {
+          const pbrMaterial = _assertAndConvertPBRMaterial(material, channel, BuiltInTextureParameter.uAng);
+
+          _setUVTextureSetting('uAng', uAng, pbrMaterial, channel);
+        }
+      }
+    );
+    parameterManager.setParameterObserver(
+      `${channel}.${BuiltInTextureParameter.vAng}`,
+      async ({ newValue, materials }) => {
+        const vAng = ParameterManager.parseNumber(newValue);
+
+        for (const material of materials) {
+          const pbrMaterial = _assertAndConvertPBRMaterial(material, channel, BuiltInTextureParameter.vAng);
+
+          _setUVTextureSetting('vAng', vAng, pbrMaterial, channel);
+        }
+      }
+    );
+    parameterManager.setParameterObserver(
+      `${channel}.${BuiltInTextureParameter.wAng}`,
+      async ({ newValue, materials }) => {
+        const wAng = ParameterManager.parseNumber(newValue);
+
+        for (const material of materials) {
+          const pbrMaterial = _assertAndConvertPBRMaterial(material, channel, BuiltInTextureParameter.wAng);
+
+          _setUVTextureSetting('wAng', wAng, pbrMaterial, channel);
+        }
+      }
+    );
+    parameterManager.setParameterObserver(
+      `${channel}.${BuiltInTextureParameter.clampU}`,
+      async ({ newValue, materials }) => {
+        const clampU = ParameterManager.parseBoolean(newValue);
+
+        for (const material of materials) {
+          const pbrMaterial = _assertAndConvertPBRMaterial(material, channel, BuiltInTextureParameter.clampU);
+
+          // we don't use _setUVTextureSetting here as the parameter ("clampU" - boolean) doesn't align with the actual
+          // texture setting ("wrapU" - enumeration)
+          const texture = _getTextureFromParameterChannel(pbrMaterial, channel);
+          if (texture) {
+            texture.wrapU = clampU ? Texture.CLAMP_ADDRESSMODE : Texture.WRAP_ADDRESSMODE;
+          }
+        }
+      }
+    );
+    parameterManager.setParameterObserver(
+      `${channel}.${BuiltInTextureParameter.clampV}`,
+      async ({ newValue, materials }) => {
+        const clampV = ParameterManager.parseBoolean(newValue);
+
+        for (const material of materials) {
+          const pbrMaterial = _assertAndConvertPBRMaterial(material, channel, BuiltInTextureParameter.clampV);
+
+          const texture = _getTextureFromParameterChannel(pbrMaterial, channel);
+          if (texture) {
+            texture.wrapV = clampV ? Texture.CLAMP_ADDRESSMODE : Texture.WRAP_ADDRESSMODE;
+          }
+        }
+      }
+    );
+    parameterManager.setParameterObserver(
+      `${channel}.${BuiltInTextureParameter.uvSet}`,
+      async ({ newValue, materials }) => {
+        const uvSet = ParameterManager.parseNumber(newValue);
+
+        for (const material of materials) {
+          const pbrMaterial = _assertAndConvertPBRMaterial(material, channel, BuiltInTextureParameter.uvSet);
+
+          const texture = _getTextureFromParameterChannel(pbrMaterial, channel);
+          if (texture) {
+            texture.coordinatesIndex = uvSet;
+          }
+        }
+      }
+    );
+  });
+
+  // this parameter is required for activating the detailmap texture, as only assigning the texture is not enough
+  parameterManager.setParameterObserver(BuiltInParameter.UseDetailmap, async ({ newValue, materials }) => {
+    const useDetailmap = ParameterManager.parseBoolean(newValue);
+
+    for (const material of materials) {
+      const materialCls = material.getClassName();
+      if (materialCls !== 'PBRMaterial') {
+        throw new Error(`Enabling detailmap for material of instance "${materialCls}" not implemented`);
+      }
+
+      const pbrMaterial = material as PBRMaterial;
+      pbrMaterial.detailMap.isEnabled = useDetailmap;
+    }
+  });
+}
+
+/**
+ * Help function for casting a material into a PBRMaterial type.\
+ * Only works if the class name confirms that this is a PBR material, throws an error for any other material type.
+ *
+ * @param channel only used for error message
+ * @param parameter only used for error message
+ */
+function _assertAndConvertPBRMaterial(material: Material, channel: string, parameter: string): PBRMaterial {
+  const materialCls = material.getClassName();
+  if (materialCls !== 'PBRMaterial') {
+    throw new Error(`Setting ${channel} ${parameter} for material of instance "${materialCls}" not implemented`);
+  }
+
+  return material as PBRMaterial;
+}
+
+/**
+ * Help function for adjusting "simple" UV texture settings, as described in the typing of `setting`
+ */
+function _setUVTextureSetting(
+  setting: keyof Pick<Texture, 'uOffset' | 'vOffset' | 'uScale' | 'vScale' | 'uAng' | 'vAng' | 'wAng'>,
+  value: number,
+  pbrMaterial: PBRMaterial,
+  channel: ParameterTextureChannelsKeys
+): void {
+  const texture = _getTextureFromParameterChannel(pbrMaterial, channel);
+
+  if (texture) {
+    texture[setting] = value;
+  } else {
+    // this is fine, the texture may be created in a later step
+    // texture settings are applied automatically after the creation is done
+  }
+}
+
+/**
+ * Get the runtime texture object from a certain channel in the material.\
+ * Only returns the texture if it's from type "Texture".
+ */
+function _getTextureFromParameterChannel(
+  pbrMaterial: PBRMaterial,
+  channel: ParameterTextureChannelsKeys
+): Texture | undefined {
+  let baseTexture: BaseTexture | null;
+
+  if (channel === 'metallicRoughnessTexture') {
+    baseTexture = pbrMaterial.metallicTexture;
+  } else if (channel === 'detailmapTexture') {
+    baseTexture = pbrMaterial.detailMap.texture;
+  } else {
+    // most times it's a direct assignment, special cases are handled above
+    baseTexture = pbrMaterial[channel];
+  }
+
+  // only return "Texture" types
+  return baseTexture instanceof Texture ? baseTexture : undefined;
+}
+
+/**
+ * Assign runtime texture to the dedicated channel in the PBR material
+ */
+function _assignTextureParameterChannel(
+  texture: Texture,
+  pbrMaterial: PBRMaterial,
+  channel: ParameterTextureChannelsKeys
+): void {
+  if (channel === 'metallicRoughnessTexture') {
+    pbrMaterial.metallicTexture = texture;
+  } else if (channel === 'detailmapTexture') {
+    pbrMaterial.detailMap.texture = texture;
+  } else {
+    pbrMaterial[channel] = texture;
+  }
+}
+
+/**
+ * Similar to `_getTextureFromParameterChannel`, whereas the input is a plain JSON object instead of a runtime material
+ */
+function _getTextureObjFromParameterChannel(materialObj: object, channel: ParameterTextureChannelsKeys): object {
+  let textureObj: object | undefined;
+
+  if (channel === 'metallicRoughnessTexture') {
+    textureObj = (materialObj as any).metallicTexture;
+  } else if (channel === 'detailmapTexture') {
+    textureObj = (materialObj as any).detailMap?.texture;
+  } else {
+    textureObj = (materialObj as any)[channel];
+  }
+
+  return textureObj ?? {};
+}

package/src/manager/material-manager.ts

@@ -3,17 +3,23 @@ import {
   BaseTexture,
   Material,
   StandardMaterial,
+  TagNamingStrategy,
   Viewer,
   ViewerError,
   ViewerErrorIds,
   ViewerEvent,
 } from '../index';
+import * as CloningHelper from '../internal/cloning-helper';
 import {
   clearInternalMetadataValue,
   getInternalMetadataValue,
   setInternalMetadataValue,
 } from '../internal/metadata-helper';
 
+export type MaterialCloneOptions = {
+  tagNamingStrategy?: TagNamingStrategy;
+};
+
 /**
  * Manager for material related tasks
  */
@@ -24,6 +30,7 @@ export class MaterialManager {
    */
   public static readonly CBN_FALLBACK_MATERIAL_NAME = '$fallback';
 
+  protected _clonedMaterials: { [name: string]: Material } = {};
   protected _createMaterialPromises: { [materialId: string]: Promise<Material | null> } = {};
 
   /** @internal */
@@ -89,6 +96,61 @@ export class MaterialManager {
     return chosenMaterial as Material;
   }
 
+  /**
+   * Creates a clone of a material.\
+   * The clones tags will be adjusted according to the "tagNamingStrategy" option.
+   * Predefined material parameters will be applied to the material right away.
+   */
+  public async cloneMaterial(
+    materialId: string,
+    newMaterialId: string,
+    options?: MaterialCloneOptions
+  ): Promise<Material> {
+    const existingMaterial = this._clonedMaterials[newMaterialId];
+    if (existingMaterial) {
+      throw new ViewerError({
+        id: ViewerErrorIds.MaterialAlreadyExists,
+        message: `Can't create clone as material "${newMaterialId}" already exists`,
+      });
+    }
+
+    const sourceMaterial = await this.getOrCreateMaterial(materialId);
+    const clonedMaterial = CloningHelper.cloneMaterial(sourceMaterial, newMaterialId, options?.tagNamingStrategy);
+
+    await this.viewer.parameterManager.applyParameterValuesToMaterial(clonedMaterial);
+
+    this._clonedMaterials[newMaterialId] = clonedMaterial;
+
+    return clonedMaterial;
+  }
+
+  /**
+   * Removes a cloned material from the scene and from the internal material clone storage.\
+   * Also remove all parameter entries from this material.
+   */
+  public deleteClonedMaterial(materialId: string): void {
+    const material = this._clonedMaterials[materialId];
+    if (!material) {
+      throw new ViewerError({
+        id: ViewerErrorIds.NotAClonedMaterial,
+        message: `Can't delete material "${materialId}" as there is no cloned material with that id`,
+      });
+    }
+
+    this.viewer.parameterManager.removeParameterEntriesOfMaterial(material);
+
+    material.dispose(true, true);
+
+    delete this._clonedMaterials[materialId];
+  }
+
+  /**
+   * Removes all cloned materials from the scene and the internal material clone storage
+   */
+  public deleteAllClonedMaterials(): void {
+    Object.keys(this._clonedMaterials).forEach(materialId => this.deleteClonedMaterial(materialId));
+  }
+
   protected async _createMaterial(materialId: string, mesh?: AbstractMesh): Promise<Material> {
     if (materialId === MaterialManager.CBN_FALLBACK_MATERIAL_NAME) {
       const fallbackMaterial = new StandardMaterial(MaterialManager.CBN_FALLBACK_MATERIAL_NAME, this.viewer.scene);

package/src/manager/model-manager.ts

@@ -61,9 +61,7 @@ export class ModelManager {
    */
   public static readonly CBN_FALLBACK_MODEL_ASSET_NAME = '$fallback';
 
-  protected _modelAssets: {
-    [name: string]: Model;
-  } = {};
+  protected _modelAssets: { [name: string]: Model } = {};
   protected _fallbackModelAsset: Model = {
     name: ModelManager.CBN_FALLBACK_MODEL_ASSET_NAME,
     url: '',
@@ -239,13 +237,14 @@ export class ModelManager {
    *
    * @param show show model immediately after cloning
    * @param options additional options for the cloning procedure, like renaming algorithms
+   * @returns asset container for further processing of the clone
    */
   public async cloneModel(
     name: string,
     newModelName: string,
     show: boolean = true,
     options?: ModelCloneOptions
-  ): Promise<void> {
+  ): Promise<AssetContainer> {
     const sourceModel = this._getModel(name);
     if (!sourceModel) {
       throw new ViewerError({
@@ -288,10 +287,13 @@ export class ModelManager {
     if (show) {
       await this._showModel(clonedModel);
     }
+
+    return clonedModel.assetContainer;
   }
 
   /**
    * Removes a cloned model from the scene and from the internal model storage.\
+   * Also removes parameter entries from all nodes of the model.\
    * Deleted clones can not be shown again.
    */
   public deleteClonedModel(name: string): void {
@@ -310,13 +312,17 @@ export class ModelManager {
       });
     }
 
+    // parameter entries of deleted model can get in the way when recreating a clone with the same node names
+    // that's why it's benefitial to wipe the parameter entries of the model as well after removing it
+    this.viewer.parameterManager.removeParameterEntriesOfModel(model.assetContainer);
+
     model.assetContainer.dispose();
 
     delete this._modelAssets[name];
   }
 
   /**
-   * Removes all cloned models from the scene and the internal model storage.
+   * Removes all cloned models from the scene and the internal model storage
    */
   public deleteAllClonedModels(): void {
     const clonedModelNames = Object.values(this._modelAssets)