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

package/src/internal/tags-helper.ts

@@ -1,41 +1,43 @@
-import { Material, Node } from '../index';
-import { Tags } from '@babylonjs/core/Misc/tags';
-
-/**
- * This is a wrapper around Babylon.js Tags API, as the API is really clunky to use
- */
-
-type TagTarget = Node | Material;
-
-export function hasTag(object: TagTarget, tag: string): boolean {
-  return Tags.MatchesQuery(object, tag);
-}
-
-export function getTags(object: TagTarget): string[] {
-  const tagsObject = Tags.GetTags(object, false) ?? {};
-  const tags = Object.keys(tagsObject);
-
-  return tags;
-}
-
-export function setTags(object: TagTarget, tags: string[]): void {
-  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 {
-  Tags.AddTagsTo(object, tagsString);
-}
-
-export function cloneTags(sourceObject: TagTarget, destinationObject: TagTarget): void {
-  if (Tags.HasTags(sourceObject)) {
-    Tags.AddTagsTo(destinationObject, Tags.GetTags(sourceObject, true));
-  }
-}
+import { Material, Node } from '../index';
+import { Tags } from '@babylonjs/core/Misc/tags';
+
+/**
+ * This is a wrapper around Babylon.js Tags API, as the API is really clunky to use
+ */
+
+type TagTarget = Node | Material;
+
+export function hasTag(object: TagTarget, tag: string): boolean {
+  return Tags.MatchesQuery(object, tag);
+}
+
+export function getTags(object: TagTarget): string[] {
+  const tagsObject = Tags.GetTags(object, false) ?? {};
+  const tags = Object.keys(tagsObject);
+
+  return tags;
+}
+
+export function setTags(object: TagTarget, tags: string[]): void {
+  deleteAllTags(object);
+  const tagsString = tags.join(' ');
+  Tags.AddTagsTo(object, tagsString);
+}
+
+export function setTagsAsString(object: TagTarget, tagsString: string): void {
+  deleteAllTags(object);
+  Tags.AddTagsTo(object, tagsString);
+}
+
+export function cloneTags(sourceObject: TagTarget, destinationObject: TagTarget): void {
+  if (Tags.HasTags(sourceObject)) {
+    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 ?? {};
+}