@combeenation/3d-viewer 6.5.0 → 7.0.0-beta1

package/src/api/util/babylonHelper.ts

@@ -1,4 +1,5 @@
 import { DottedPath } from '../classes/dottedPath';
+import { Event, emitter } from '../classes/event';
 import { defaultEnvHelperColor, defaultSceneClearColor } from '../internal/sceneSetup';
 import {
   addMissingMaterialObserver,
@@ -23,11 +24,12 @@ import { InstancedMesh } from '@babylonjs/core/Meshes/instancedMesh';
 import { Mesh } from '@babylonjs/core/Meshes/mesh';
 import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
 import { Observable } from '@babylonjs/core/Misc/observable';
+import { Tags } from '@babylonjs/core/Misc/tags';
 import { Tools } from '@babylonjs/core/Misc/tools';
 import { Node } from '@babylonjs/core/node';
 import { Scene } from '@babylonjs/core/scene';
 import { Nullable } from '@babylonjs/core/types';
-import { cloneDeep, get, has, merge } from 'lodash-es';
+import { cloneDeep, get, has, merge, uniq } from 'lodash-es';
 
 const backgroundDomeName = 'BackgroundDome_ViewerGenerated';
 const envHelperMetadataName = 'viewerEnvHelper';
@@ -82,21 +84,26 @@ const getDottedPathForNode = function (node: Node): DottedPath {
 
 /**
  * @param node
+ * @param nodeNamingStrategy
  * @param predicate
  * @param deep
  * @return TransformNode | null
  */
 const cloneTransformNode = function (
   node: TransformNode,
+  nodeNamingStrategy: NodeNamingStrategy,
   predicate?: (node: TransformNode) => boolean,
   deep: boolean = true
 ): TransformNode | null {
   if (predicate && !predicate(node)) {
     return null;
   }
-  const clone = node.clone(node.name, node.parent, true);
+  const newName = nodeNamingStrategy.handler(node, nodeNamingStrategy.payload);
+  const clone = node.clone(newName, node.parent, true);
   if (clone) {
+    clone.id = newName;
     clone.metadata = cloneDeep(node.metadata);
+    injectNodeMetadata(clone, { cloneSource: node }, false);
     // if the cloned node is of type InstancedMesh, due to a bug(?),
     // the InstancedMesh.isEnabled state may have changed after cloning.
     // in that case, set the clone's enabled state to the original's state
@@ -107,7 +114,7 @@ const cloneTransformNode = function (
   if (deep) {
     const children = node.getChildTransformNodes(true);
     children.forEach(child => {
-      const clonedChild = cloneTransformNode(child, predicate, deep);
+      const clonedChild = cloneTransformNode(child, nodeNamingStrategy, predicate, deep);
       if (clonedChild) {
         clonedChild.parent = clone;
       }
@@ -174,7 +181,7 @@ const injectNodeMetadata = function (node: Node, metadata: {}, deep: boolean = t
  */
 const assertTransformNode = function (
   node: TransformNode,
-  assertCallable: CallableFunction,
+  assertCallable: (node: TransformNode, ...args: any[]) => void,
   callableParameters: any[] = [],
   deep: boolean = true
 ) {
@@ -185,6 +192,24 @@ const assertTransformNode = function (
   }
 };
 
+/**
+ * @param node
+ * @param parameter
+ */
+const assertMeshCapability = function (node: TransformNode, parameter: string) {
+  if (!(node instanceof AbstractMesh)) {
+    const cls = node.getClassName();
+    throw new Error(
+      `Changing parameter "${parameter}" of a(n) ${cls} is not supported. Tried to change node "${node.id}".`
+    );
+  }
+  if (node instanceof InstancedMesh) {
+    throw new Error(
+      `Changing parameter "${parameter}" of an InstancedMesh is not supported. Tried to change node "${node.id}".`
+    );
+  }
+};
+
 /**
  * @param node
  * @param deep
@@ -372,15 +397,9 @@ const changeEnvironment = function (scene: Scene, envDef: EnvironmentDefinition)
  * Finally the material will not be applied before all its textures have been loaded. In this way "flickering" effects
  * will be avoided, since the material would be incomplete without its loaded textures.
  */
-const setMaterial = function (
-  scene: Scene,
-  node: TransformNode,
-  materialId: string,
-  deep: boolean = true,
-  variant?: Variant
-) {
+const setMaterial = function (node: TransformNode, materialId: string, deep: boolean = true, variant?: Variant) {
   if (node instanceof AbstractMesh) {
-    const materialExists = scene.getMaterialById(materialId);
+    const materialExists = node.getScene().getMaterialById(materialId);
     const hasMissingMaterial = has(node.metadata, missingMaterialMetadataName);
     const deferMaterialCreation = !materialExists && !node.isEnabled();
     if (deferMaterialCreation) {
@@ -391,9 +410,9 @@ const setMaterial = function (
         addMissingMaterialObserver(node);
       }
     } else {
-      // create material an apply it when textures have been loaded
-      const material = getOrCreateMaterial(scene, materialId, variant);
-      applyMaterialAfterTexturesLoaded(material, node);
+      // create material and apply it when textures have been loaded
+      const material = getOrCreateMaterial(node.getScene(), materialId, variant);
+      applyMaterial(material, node).then(() => emitter.emit(Event.MESH_MATERIAL_APPLIED, node, material));
 
       if (hasMissingMaterial) {
         delete node.metadata[missingMaterialMetadataName];
@@ -403,7 +422,7 @@ const setMaterial = function (
   // recursively set materials on children (if desired)
   if (deep) {
     for (const child of node.getChildTransformNodes(true)) {
-      setMaterial(scene, child, materialId, deep, variant);
+      setMaterial(child, materialId, deep, variant);
     }
   }
 };
@@ -429,10 +448,10 @@ const getOrCreateMaterial = function (scene: Scene, materialId: string, variant?
 };
 
 /**
- * Waits until the materials textures are loaded and sets the material on the node if there is no newer "set material"
- * request
+ * Waits until the materials textures are loaded and shaders are compiled.
+ * Then sets the material on the node if there is no newer "set material" request
  */
-const applyMaterialAfterTexturesLoaded = async function (material: Material, node: AbstractMesh) {
+const applyMaterial = async function (material: Material, node: AbstractMesh) {
   // set current material id as last valid id, in this case all previously set materials on the node will be invalidated
   injectNodeMetadata(node, { [materialWaitingToBeSetMetadataName]: material.id }, false);
 
@@ -451,7 +470,7 @@ const applyMaterialAfterTexturesLoaded = async function (material: Material, nod
   await Promise.all([promTexturesReady, promMaterialCompiled]);
 
   // textures ready, now check if the material is still up-to-date
-  if (material.id === node.metadata[materialWaitingToBeSetMetadataName]) {
+  if (material.id === node.metadata?.[materialWaitingToBeSetMetadataName]) {
     node.material = material;
     delete node.metadata[materialWaitingToBeSetMetadataName];
   }
@@ -505,6 +524,7 @@ const setMaterialColor = function (node: TransformNode, color: Color3, deep: boo
       default:
         throw new Error(`Setting color for material of instance "${materialCls}" not implemented (yet).`);
     }
+    setMaterial(node, node.material.id, false);
   }
   if (deep) {
     node.getChildTransformNodes(true).forEach(child => setMaterialColor(child, color, deep));
@@ -529,6 +549,7 @@ const setMaterialTexture = function (node: TransformNode, texture: Texture, deep
       default:
         throw new Error(`Setting texture for material of instance "${materialCls}" not implemented (yet).`);
     }
+    setMaterial(node, node.material.id, false);
   }
   if (deep) {
     node.getChildTransformNodes(true).forEach(child => setMaterialTexture(child, texture, deep));
@@ -550,6 +571,7 @@ const setMaterialMetallness = function (node: TransformNode, metallness: number,
       default:
         throw new Error(`Setting metallness for material of instance "${materialCls}" not implemented (yet).`);
     }
+    setMaterial(node, node.material.id, false);
   }
   if (deep) {
     node.getChildTransformNodes(true).forEach(child => setMaterialMetallness(child, metallness, deep));
@@ -574,6 +596,7 @@ const setMaterialRoughness = function (node: TransformNode, roughness: number, d
       default:
         throw new Error(`Setting roughness for material of instance "${materialCls}" not implemented (yet).`);
     }
+    setMaterial(node, node.material.id, false);
   }
   if (deep) {
     node.getChildTransformNodes(true).forEach(child => setMaterialRoughness(child, roughness, deep));
@@ -704,6 +727,56 @@ const isTextureWithOnLoadObservable = function (texture: BaseTexture): texture i
   return !!(texture as BaseTextureWithOnLoadObservable).onLoadObservable;
 };
 
+/**
+ * @param objects
+ * @param tagMapping
+ */
+const mapTags = function (objects: object[], tagMapping: TagMapping): string[] {
+  let affectedTags: string[] = [];
+  for (const object of objects) {
+    const oldTags = Object.keys(Tags.GetTags(object, false) ?? {});
+    const mappedTags = oldTags.map(t => tagMapping[t] || t);
+    Tags.RemoveTagsFrom(object, oldTags.join(' '));
+    Tags.AddTagsTo(object, mappedTags.join(' '));
+    affectedTags = [...affectedTags, ...mappedTags];
+  }
+  return uniq(affectedTags);
+};
+
+/**
+ * Gets an array of ids for nodeIds that exist in both TransformNode arrays.
+ * @param nodes1
+ * @param nodes2
+ * @param predicate
+ */
+const intersectingNodeNames = function (nodes1: Node[], nodes2: Node[], predicate?: (node: Node) => boolean): string[] {
+  const nodeNames1 = nodes1.filter(n => !predicate || predicate(n)).map(n => n.name);
+  const nodesNames2 = nodes2.filter(n => !predicate || predicate(n)).map(n => n.name);
+  return nodeNames1.filter(n1 => nodesNames2.includes(n1));
+};
+
+/**
+ * Gets an array of ids for duplicate nodeIds in given node array.
+ * @param nodes
+ * @param predicate
+ */
+const duplicateNodeNames = function (nodes: Node[], predicate?: (node: Node) => boolean): string[] {
+  const nodeNames = nodes.filter(n => !predicate || predicate(n)).map(n => n.name);
+  return nodeNames.filter((v, i, self) => self.indexOf(v) !== i);
+};
+
+/**
+ * Reports duplicate nodeIds.
+ * @param nodeNames
+ */
+const reportDuplicateNodeNames = function (nodeNames: string[]): void {
+  if (nodeNames.length > 0) {
+    const warn = `There are duplicate nodeNames: ${nodeNames.join(', ')}`;
+    console.warn(`!!! Warning !!!\n${warn}`);
+    window.Cbn?.Assets.reportDuplicateNodeName(nodeNames);
+  }
+};
+
 export {
   getRootNode,
   isTextureWithOnLoadObservable,
@@ -713,9 +786,10 @@ export {
   cloneNodeWithParents,
   cloneTransformNodeMaterial,
   getOrCreateMaterial,
-  applyMaterialAfterTexturesLoaded,
+  applyMaterial,
   injectNodeMetadata,
   assertTransformNode,
+  assertMeshCapability,
   activateTransformNode,
   deactivateTransformNode,
   enableNodeWithParents,
@@ -736,4 +810,8 @@ export {
   changeEnvironment,
   backgroundDomeName,
   envHelperMetadataName,
+  mapTags,
+  intersectingNodeNames,
+  duplicateNodeNames,
+  reportDuplicateNodeNames,
 };

package/src/api/util/globalTypes.ts

@@ -2,6 +2,7 @@
 type Viewer = import('../classes/viewer').Viewer;
 type Variant = import('../classes/variant').Variant;
 type VariantInstance = import('../classes/variantInstance').VariantInstance;
+type VariantParameterizable = import('../classes/variantParameterizable').VariantParameterizable;
 /**
  * Alias for {@link Element} which can be used to prevent name clashes with the web APIs
  * [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) class
@@ -11,6 +12,8 @@ type DottedPath = import('../classes/dottedPath').DottedPath;
 type ViewerLight = import('../classes/viewerLight').ViewerLight;
 type SceneManager = import('../manager/sceneManager').SceneManager;
 
+type FuzzyMap<K, V> = import('../classes/fuzzyMap').FuzzyMap<K, V>;
+
 // global accessible types imported from BabylonJS
 type Scene = import('@babylonjs/core/scene').Scene;
 type Vector3 = import('@babylonjs/core/Maths/math.vector').Vector3;
@@ -42,6 +45,10 @@ type IExportOptions = import('@babylonjs/serializers/glTF/2.0').IExportOptions;
 
 type EventEmitter = import('eventemitter3');
 
+type Undefinable<T> = T | undefined;
+
+type Nullable<T> = T | null;
+
 // some more global accessible types
 type PathDefinitions = {
   include: string[];
@@ -368,7 +375,13 @@ type ParsedParameterBag = {
 
 type DottedPathArgument = string | string[] | DottedPath;
 
-type ParameterObserver = (object: any, oldValue: ParameterValue, newValue: ParameterValue) => void;
+type ParameterObserverResult = any;
+
+type ParameterObserver = (
+  payload: any,
+  oldValue: Undefinable<ParameterValue>,
+  newValue: ParameterValue
+) => ParameterObserverResult;
 
 type PlacementDefinitions = {
   [name: string]: PlacementDefinition;
@@ -435,3 +448,45 @@ type SpecGenerationData = {
   name: string;
   url: string;
 };
+
+type TagMapping = {
+  [tagName: string]: string;
+};
+
+type TagManagerSubject = {
+  tagName?: string;
+  nodeName?: string;
+};
+
+type TagManagerParameterObserver = (payload: TagManagerParameterObserverPayload) => ParameterObserverResult;
+
+type TagManagerParameterBag = FuzzyMap<TagManagerSubject, ParameterBag>;
+
+type TagManagerParameterObserverBag = Map<string, TagManagerParameterObserver>;
+
+type TagManagerParameterObserverPayload = {
+  subject: TagManagerSubject;
+  nodes: TransformNode[];
+  newValue: ParameterValue;
+  oldValue: Undefinable<ParameterValue>;
+};
+
+type TagManagerParameterValue = {
+  tagName?: string;
+  nodeName?: string;
+  parameterName: string;
+  value: ParameterValue;
+};
+
+type NodeNamingStrategyPayload = {
+  variantInstance: VariantInstance;
+  variant: Variant;
+  variantParameterizable: VariantParameterizable;
+};
+
+type NodeNamingStrategyHandler = (node: TransformNode, payload: NodeNamingStrategyPayload) => string;
+
+type NodeNamingStrategy = {
+  handler: NodeNamingStrategyHandler;
+  payload: NodeNamingStrategyPayload;
+};

package/src/api/util/sceneLoaderHelper.ts

@@ -1,4 +1,5 @@
-import { applyMaterialAfterTexturesLoaded, getOrCreateMaterial, injectNodeMetadata } from './babylonHelper';
+import { Event, emitter } from '../classes/event';
+import { applyMaterial, getOrCreateMaterial, injectNodeMetadata } from './babylonHelper';
 import { sleep } from './resourceHelper';
 import { ISceneLoaderPlugin } from '@babylonjs/core/Loading/sceneLoader';
 import { Material } from '@babylonjs/core/Materials/material';
@@ -67,7 +68,9 @@ export const getMaterialPostLoadObserver = function (concerningMesh: Mesh) {
     const missingMatId = concerningMesh.metadata[missingMaterialMetadataName];
     // get material and apply it on the concerning mesh after all textures have been loaded
     const material = getOrCreateMaterial(concerningMesh.getScene(), missingMatId);
-    applyMaterialAfterTexturesLoaded(material, concerningMesh);
+    applyMaterial(material, concerningMesh).then(() =>
+      emitter.emit(Event.MESH_MATERIAL_APPLIED, concerningMesh, material)
+    );
     // since the material is there now, we do not need the related metadata tag anymore
     delete concerningMesh.metadata[missingMaterialMetadataName];
 
@@ -134,6 +137,22 @@ export const addMissingMaterialObserver = function (node: BjsNode) {
   }
 };
 
+export const removeMissingMaterialObserver = function (node: BjsNode) {
+  // set the concerning node, i.e. the node the observer should check for missing material.
+  // for instanced meshes, we want the sourcemesh here.
+  const concerningNode = node instanceof InstancedMesh ? node.sourceMesh : (node as Mesh);
+  let currNode: Nullable<BjsNode> = node;
+  while (currNode) {
+    enableObserverMap[concerningNode.id]?.forEach(entry => {
+      if (entry.currNodeId === currNode?.id) {
+        currNode.onEnabledStateChangedObservable.remove(entry.observer);
+      }
+    });
+    currNode = currNode.parent;
+  }
+  delete enableObserverMap[concerningNode.id];
+};
+
 /**
  * Look up the provided materials (see library import) and create and return one if found.
  *

package/src/dev.ts

@@ -3,6 +3,7 @@ import {
   afterBootstrap,
   beforeBootstrap,
   createSpec,
+  createTagManagerParameterValues,
   createUIelements,
   getMaterial,
   mockMaterials,
@@ -33,6 +34,7 @@ window.Cbn = {
     assertMaterialExists(materialId: string): boolean {
       return true;
     },
+    reportDuplicateNodeName(nodeNameOrArrayOfNodeNames: string | string[]): void {},
   },
 };
 
@@ -50,7 +52,7 @@ async function bootstrapViewer() {
   const viewer = new Viewer(canvas, createSpec());
   await beforeBootstrap(viewer);
   try {
-    await viewer.bootstrap();
+    await viewer.bootstrap(createTagManagerParameterValues(viewer));
   } catch (e) {
     console.error(e);
   }

package/src/index.ts

@@ -17,6 +17,7 @@ import { ViewerLight } from './api/classes/viewerLight';
 import { AnimationManager } from './api/manager/animationManager';
 import { GltfExportManager } from './api/manager/gltfExportManager';
 import { SceneManager } from './api/manager/sceneManager';
+import { TagManager } from './api/manager/tagManager';
 import { VariantInstanceManager } from './api/manager/variantInstanceManager';
 import { SpecStorage } from './api/store/specStorage';
 import * as BabylonHelper from './api/util/babylonHelper';
@@ -95,4 +96,5 @@ export {
   BabylonHelper,
   GltfExportManager,
   SpecStorage,
+  TagManager,
 };

package/src/types.d.ts

@@ -23,6 +23,13 @@ interface Window {
            * @param materialId
            */
           assertMaterialExists(materialId: string): boolean;
+
+          /**
+           * Warns user about duplicate nodeNames on scene.
+           *
+           * @param nodeNameOrArrayOfNodeNames
+           */
+          reportDuplicateNodeName(nodeNameOrArrayOfNodeNames: string | string[]): void;
         };
       };
 }