@combeenation/3d-viewer 14.1.0 → 15.0.0

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/parameter-manager.ts

@@ -14,6 +14,12 @@ import {
 import { getInternalMetadataValue, setInternalMetadataValue } from '../internal/metadata-helper';
 import { paintableParameterObserver } from '../internal/paintable-helper';
 import { getTags, hasTag } from '../internal/tags-helper';
+import {
+  BuiltInTextureParameter,
+  BuiltInTextureParameterKeys,
+  ParameterTextureChannelsKeys,
+  createBuiltInTextureParameter,
+} from '../internal/texture-parameter-helper';
 import { capitalize, isString } from 'lodash-es';
 
 /**
@@ -28,6 +34,18 @@ export const BuiltInParameter = {
   Color: 'color',
   Roughness: 'roughness',
   Metallic: 'metallic',
+  /**
+   * Texture parameters are always a combination of the channel (e.g. `albedoTexture`) and a sub parameter
+   * (e.g. `uScale`). Use this function to create the parameter accordingly
+   * (e.g. createTextureParameter("albedoTexture", "uScale")).
+   */
+  createTextureParameter: (channel: ParameterTextureChannelsKeys, parameter: BuiltInTextureParameterKeys): string =>
+    `${channel}.${parameter}`,
+  UseDetailmap: 'useDetailmap',
+};
+
+/** @ignore @deprected Use "texture parameters" {@link BuiltInParameter}.`createTextureParameter` instead */
+export const LegacyParameter = {
   Paintable: 'paintable',
 };
 
@@ -350,6 +368,40 @@ export class ParameterManager {
     await this._applyParameterValues(parameterEntriesToApply);
   }
 
+  /**
+   * Applies subset of texture parameter values which are targeting a certain texture channel in a material.\
+   * This can be useful when updating texture settings (e.g. uScale) before the texture is actually created.
+   *
+   * @internal
+   */
+  public async applyTextureSettingsParameter(
+    material: PBRMaterial,
+    channel: ParameterTextureChannelsKeys
+  ): Promise<void> {
+    const tags = getTags(material);
+
+    const parameterEntriesToApply: ParameterEntry[] = [];
+    tags.forEach(tagName => {
+      const tagParamEntries = this._getEntriesOfSubject({ tagName });
+      parameterEntriesToApply.push(...tagParamEntries);
+    });
+
+    const materialParamEntries = this._getEntriesOfSubject({ materialName: material.id });
+    parameterEntriesToApply.push(...materialParamEntries);
+
+    const textureParameterEntriesToApply = parameterEntriesToApply.filter(parameterEntry => {
+      const paramPath = parameterEntry.parameterName.split('.');
+      // find texture parameters of this channel, e.g. "albedoTexture.uScale"
+      // "image" should not be applied here as this is part of the texture initialization anyway
+      const isTextureParamOfChannel =
+        paramPath.length === 2 && paramPath[0] === channel && paramPath[1] !== BuiltInTextureParameter.image;
+
+      return isTextureParamOfChannel;
+    });
+
+    await this._applyParameterValues(textureParameterEntriesToApply);
+  }
+
   /**
    * @returns Desired parameter value of a certain node.
    * Tags are considered as well but have lower priority than node parameters, as these are more specific.
@@ -405,9 +457,19 @@ export class ParameterManager {
 
       for (const node of nodes) {
         if (visible) {
-          const deferredMaterial = getInternalMetadataValue(node, 'deferredMaterial');
-          if (deferredMaterial) {
-            await this.viewer.materialManager.setMaterialOnMesh(deferredMaterial as string, node as AbstractMesh);
+          // if a mesh gets visible by this operation we have to activate the assigned material which is stored in the
+          // internal metadata
+          // => consider child meshes as well (CB-10143)
+          const activatedNodes = [node, ...node.getChildMeshes(false)];
+          for (const activatedNode of activatedNodes) {
+            const deferredMaterial = getInternalMetadataValue(activatedNode, 'deferredMaterial');
+            if (deferredMaterial) {
+              await this.viewer.materialManager.setMaterialOnMesh(
+                deferredMaterial as string,
+                // this cast is fine, as deferred material can only be set on meshes
+                activatedNode as AbstractMesh
+              );
+            }
           }
 
           node.setEnabled(true);
@@ -422,9 +484,22 @@ export class ParameterManager {
       for (const node of nodes) {
         // NOTE: don't use node.isEnabled() as visibility observer is probably called in same cycle but later
         // however the parameter value is already correct at this stage
-        const rawVisibleValue = this.getParameterValueOfNode(node, BuiltInParameter.Visible);
+        // we have to go through all parents as well, because a parent may have been set to false, which also disables
+        // this child node
+        let curNode: TransformNode | null = node;
+        let visibleByParameter: boolean | undefined = undefined;
+        while (curNode && visibleByParameter !== false) {
+          const curNodeVisibleByParameter = this.getParameterValueOfNode(curNode, BuiltInParameter.Visible);
+          if (curNodeVisibleByParameter !== undefined) {
+            visibleByParameter = curNodeVisibleByParameter as boolean;
+          }
+          curNode = curNode.parent as TransformNode;
+        }
+
+        // parameter visibility has priority, but if the visiblity is not controlled by the parameter use the plain
+        // Babylon.js isEnabled() check
         const visible =
-          rawVisibleValue !== undefined ? ParameterManager.parseBoolean(rawVisibleValue) : node.isEnabled();
+          visibleByParameter !== undefined ? ParameterManager.parseBoolean(visibleByParameter) : node.isEnabled();
         if (visible) {
           // TODO WTT: check mesh type and throw error if it doesn't fit
           // think of creating a framework with type guards (isMesh, canHaveMaterial, ...) around this
@@ -503,9 +578,12 @@ export class ParameterManager {
         }
       }
     });
-    this.setParameterObserver(BuiltInParameter.Paintable, async ({ newValue, materials }) => {
+    this.setParameterObserver(LegacyParameter.Paintable, async ({ newValue, materials }) => {
       paintableParameterObserver(newValue, materials, this.viewer.scene);
     });
+
+    // texture parameter use a more generic approach (`channel`.`parameter`) and are therefore coded in a dedicated file
+    createBuiltInTextureParameter(this, this.viewer.scene);
   }
 
   /**

package/src/viewer-error.ts

@@ -26,6 +26,7 @@ export const ViewerErrorIds = {
   ModelIsNotAClone: 'ModelIsNotAClone',
   AssetLoadingFailed: 'AssetLoadingFailed',
   MaterialCouldNotBeParsed: 'MaterialCouldNotBeParsed',
+  TextureCouldNotBeParsed: 'TextureCouldNotBeParsed',
 };
 
 /** @internal */

package/src/viewer.ts

@@ -112,7 +112,7 @@ export class Viewer {
     return this._scene;
   }
   get engine(): Engine {
-    return this.scene.getEngine();
+    return this.scene.getEngine() as Engine;
   }
   get cameraManager(): CameraManager {
     return this._cameraManager;