@combeenation/3d-viewer 12.4.1 → 13.0.0

package/src/internal/cloningHelper.ts

@@ -0,0 +1,225 @@
+import {
+  AbstractMesh,
+  AssetContainer,
+  InstancedMesh,
+  Mesh,
+  MorphTargetManager,
+  NodeNamingStrategy,
+  Scene,
+  TagNamingStrategy,
+  TransformNode,
+} from '../index';
+import {
+  clearInternalMetadataValue,
+  cloneInternalMetadata,
+  cloneMetadata,
+  getInternalMetadataValue,
+  setInternalMetadataValue,
+} from './metadataHelper';
+import { cloneTags, getTags, setTags } from './tagsHelper';
+
+const _defaultNodeNamingStrategy: NodeNamingStrategy = (node: TransformNode, newModelName: string): string => {
+  return `${node.name}.${newModelName}`;
+};
+const _defaultTagNamingStrategy: TagNamingStrategy = (tag: string, newModelName: string): string => {
+  // don't rename tags by default
+  return tag;
+};
+
+/**
+ * Clones the node hierarchy of the asset container with some special treatment that differs from Babylon.js default
+ * cloning behaviour, such as:
+ * - create new instances of morph target manager
+ * - deep cloning internal metadata
+ * - deep cloning metadata and tags for instanced meshes
+ * - reassigns source meshes in cloned asset container
+ * Furthermore there is the possibility to adjust naming of nodes and tags in the cloned asset container
+ */
+export function cloneModelAssetContainer(
+  sourceAssetContainer: AssetContainer,
+  newModelName: string,
+  renaming: {
+    nodeNamingStrategy?: NodeNamingStrategy;
+    tagNamingStrategy?: TagNamingStrategy;
+  },
+  scene: Scene
+): AssetContainer {
+  const targetAssetContainer = new AssetContainer(scene);
+
+  sourceAssetContainer.rootNodes.forEach(node => {
+    if (node instanceof TransformNode) {
+      // this is the actual node tree cloning procedure
+      _cloneNode(node, newModelName, null, targetAssetContainer, {
+        nodeNamingStrategy: renaming?.nodeNamingStrategy,
+        tagNamingStrategy: renaming?.tagNamingStrategy,
+      });
+    }
+  });
+
+  targetAssetContainer.populateRootNodes();
+  targetAssetContainer.rootNodes.forEach(node => {
+    if (node instanceof TransformNode) {
+      // reassigning instanced meshes can only be done after the model has been fully cloned, as we can't be sure if
+      // the source or instanced mesh is handled prior
+      _reAssignSourceMesh(node, sourceAssetContainer.meshes, targetAssetContainer.meshes);
+    }
+  });
+
+  // morph target manager is not cloned per default, therefore morph targets would affect original and cloned model at
+  // the same time, which we don't want
+  sourceAssetContainer.morphTargetManagers.forEach(sourceMTM => {
+    cloneMorphTargetManager(sourceMTM, targetAssetContainer);
+  });
+
+  _clearCloningMetadata(sourceAssetContainer);
+  _clearCloningMetadata(targetAssetContainer);
+
+  // hide immediately, so that show model code can do it's thing (scene preparation) before finally showing the model
+  targetAssetContainer.removeAllFromScene();
+
+  return targetAssetContainer;
+}
+
+/**
+ * Helper function for cloning a morph target manager and updating all the mesh assignments.
+ * Meshes need to be already available in the target asset container.
+ */
+export function cloneMorphTargetManager(
+  sourceMTM: MorphTargetManager,
+  targetAssetContainer: AssetContainer
+): MorphTargetManager {
+  const clonedMTM = sourceMTM.clone();
+
+  clonedMTM._parentContainer = targetAssetContainer;
+  targetAssetContainer.morphTargetManagers.push(clonedMTM);
+
+  targetAssetContainer.meshes.forEach(mesh => {
+    if (mesh.morphTargetManager?.uniqueId === sourceMTM.uniqueId) {
+      mesh.morphTargetManager = clonedMTM;
+    }
+  });
+
+  return clonedMTM;
+}
+
+/**
+ * The actual geometry cloning function.
+ * Calls "clone" function of dedicated Node type and recourses into children to clone the whole node tree.
+ * Adds temporary metadata for special treatment of certain node types (e.g. InstancedMesh).
+ */
+function _cloneNode(
+  node: TransformNode,
+  newModelName: string,
+  newParent: TransformNode | null,
+  assetContainer: AssetContainer,
+  renaming: {
+    nodeNamingStrategy?: NodeNamingStrategy;
+    tagNamingStrategy?: TagNamingStrategy;
+  }
+): void {
+  const nodeNamingStrategy = renaming.nodeNamingStrategy ?? _defaultNodeNamingStrategy;
+  const tagNamingStrategy = renaming.tagNamingStrategy ?? _defaultTagNamingStrategy;
+
+  const cloneName = nodeNamingStrategy(node, newModelName);
+  const clone = node.clone(cloneName, newParent, true);
+  if (!clone) {
+    throw new Error(`Cloning node "${node.name}" failed`);
+  }
+
+  clone.id = cloneName;
+  // create a deep clone for internal metadata, as the default clone function uses the same assignment of the sources
+  // internal metadata
+  cloneInternalMetadata(node, clone);
+  // ATM the assignment from clone to source is needed for reassigning instanced meshes after cloning
+  // may be usefull for other node types in the future as well
+  setInternalMetadataValue(clone, 'cloneSource', node.uniqueId);
+  setInternalMetadataValue(node, 'cloneTarget', clone.uniqueId);
+
+  if (node instanceof InstancedMesh) {
+    _cloneInstancedMeshData(node, clone as InstancedMesh);
+  }
+
+  const sourceTags = getTags(node);
+  const mappedTags = sourceTags.map(tag => tagNamingStrategy(tag, newModelName));
+  setTags(clone, mappedTags);
+
+  clone._parentContainer = assetContainer;
+  // TODO WTT: create global helper function for distinguishing between transform nodes and meshes
+  if (clone instanceof AbstractMesh) {
+    assetContainer.meshes.push(clone);
+  } else {
+    assetContainer.transformNodes.push(clone);
+  }
+
+  const children = node.getChildTransformNodes(true);
+  children.forEach(child => _cloneNode(child, newModelName, clone, assetContainer, renaming));
+}
+
+/**
+ * Cloned instanced meshes are having the same source mesh as their cloning source.
+ * However we want the cloned source mesh to be the actual source.
+ * Exchanging and reassigning is done within this function.
+ * Operates on the given `node` and all its children recursively.
+ */
+function _reAssignSourceMesh(node: TransformNode, sourceMeshes: AbstractMesh[], clonedMeshes: AbstractMesh[]): void {
+  if (node instanceof InstancedMesh) {
+    // find the cloned instance and source mesh
+    const clonedInstance = node;
+    const originalInstance = _findByUniqueId(
+      sourceMeshes,
+      getInternalMetadataValue(clonedInstance, 'cloneSource') as number
+    );
+    if (originalInstance instanceof InstancedMesh) {
+      const originalSource = originalInstance.sourceMesh;
+      const clonedSource = _findByUniqueId(
+        clonedMeshes,
+        getInternalMetadataValue(originalSource, 'cloneTarget') as number
+      );
+      if (clonedSource instanceof Mesh) {
+        // it's not possible to just exchange the source mesh => readonly property
+        // we have to create a new clone with the correct source mesh
+        const exchangedInstance = clonedInstance.clone(clonedInstance.name, clonedInstance.parent, true, clonedSource);
+        clonedInstance._parentContainer!.meshes.push(exchangedInstance);
+
+        _cloneInstancedMeshData(clonedInstance, exchangedInstance);
+
+        // re-reference the childs of the cloned instance as well
+        const childs = clonedInstance.getChildTransformNodes(true);
+        childs.forEach(child => (child.parent = exchangedInstance));
+      }
+    }
+
+    // old instance mesh is not needed anymore and can be disposed
+    clonedInstance.dispose();
+  }
+
+  // recurse into childs
+  const children = node.getChildTransformNodes(true);
+  children.forEach(child => _reAssignSourceMesh(child, sourceMeshes, clonedMeshes));
+}
+
+/**
+ * Removes metadata entries "cloneSource" and "cloneTarget" from all meshes and transform nodes inside the asset
+ * container
+ */
+function _clearCloningMetadata(assetContainer: AssetContainer): void {
+  [...assetContainer.meshes, ...assetContainer.transformNodes].forEach(node => {
+    clearInternalMetadataValue(node, 'cloneSource');
+    clearInternalMetadataValue(node, 'cloneTarget');
+  });
+}
+
+/**
+ * "InstancedMesh.clone" function doesn't clone tags and metadata, also the enabled state doesn't seem to be cloned
+ * correctly.
+ * This function adjusts the behaviour to fulfill our expectations.
+ */
+function _cloneInstancedMeshData(sourceInstancedMesh: InstancedMesh, targetInstancedMesh: InstancedMesh): void {
+  targetInstancedMesh.setEnabled(sourceInstancedMesh.isEnabled(false));
+  cloneMetadata(sourceInstancedMesh, targetInstancedMesh);
+  cloneTags(sourceInstancedMesh, targetInstancedMesh);
+}
+
+function _findByUniqueId(nodes: TransformNode[], uniqueId: number): TransformNode | undefined {
+  return nodes.find(node => node.uniqueId === uniqueId);
+}

package/src/internal/deviceHelper.ts

@@ -0,0 +1,25 @@
+import { LimitTextureSizeConfig } from '../index';
+
+/**
+ * Checks if the current device is an iPhone
+ */
+export function getIsIPhone(): boolean {
+  const isIPhone = /iPhone/.test(navigator.userAgent);
+
+  return isIPhone;
+}
+
+/**
+ * Checks if the current device is "scaled down", as defined in the Spec
+ */
+export function getIsScaledDownDevice(limitTextureSize: LimitTextureSizeConfig | false): boolean {
+  if (!limitTextureSize) {
+    // no down scaling defined
+    return false;
+  }
+
+  // check device
+  const deviceFits = limitTextureSize.devices === 'all' || (limitTextureSize.devices === 'iPhone' && getIsIPhone());
+
+  return deviceFits;
+}

package/src/{api/util → internal}/geometryHelper.ts

@@ -1,23 +1,64 @@
-import { VertexBuffer } from '@babylonjs/core/Buffers/buffer';
-import { Vector3 } from '@babylonjs/core/Maths/math.vector';
-import type { Geometry } from '@babylonjs/core/Meshes/geometry';
-import { InstancedMesh } from '@babylonjs/core/Meshes/instancedMesh';
-import { Mesh } from '@babylonjs/core/Meshes/mesh';
-import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
-import type { MorphTarget } from '@babylonjs/core/Morph/morphTarget';
-import { MorphTargetManager } from '@babylonjs/core/Morph/morphTargetManager';
-import type { FloatArray } from '@babylonjs/core/types';
+import {
+  ExcludedGeometry,
+  ExcludedGeometryList,
+  FloatArray,
+  Geometry,
+  InstancedMesh,
+  Mesh,
+  MorphTarget,
+  MorphTargetManager,
+  ParameterSubject,
+  TransformNode,
+  Vector3,
+  VertexBuffer,
+} from '../index';
+import { cloneInternalMetadata } from './metadataHelper';
+import { hasTag } from './tagsHelper';
+
+/**
+ * Find out if a node is part of a list of excluded geometry
+ * @param node BJS node
+ * @param list list of excluded geometry
+ * @returns boolean based on whether node (or one of its parents) was found in list
+ */
+export function isNodeExcluded(nodeToCheck: TransformNode, list: ExcludedGeometryList): boolean {
+  // CAUTION: node has to be the same instance
+  const checkNode = (excludedNode: TransformNode): boolean => excludedNode === nodeToCheck;
+  const checkTagManagerSubject = (excludedSubject: ParameterSubject): boolean => {
+    const nameMatches = !!excludedSubject.nodeName && excludedSubject.nodeName === nodeToCheck.name;
+    const tagMatches = !!excludedSubject.tagName && hasTag(nodeToCheck, excludedSubject.tagName);
+    return nameMatches || tagMatches;
+  };
+  const check = (geometryToExclude: ExcludedGeometry): boolean => {
+    if (geometryToExclude instanceof TransformNode) {
+      return checkNode(geometryToExclude);
+    }
+    if ((geometryToExclude as ParameterSubject).tagName || (geometryToExclude as ParameterSubject).nodeName) {
+      return checkTagManagerSubject(geometryToExclude as ParameterSubject);
+    }
+    return false;
+  };
+
+  let isExcluded = list.some(geometryToExclude => check(geometryToExclude));
+  // consider parent as well
+  if (!isExcluded && nodeToCheck.parent instanceof TransformNode) {
+    isExcluded = isNodeExcluded(nodeToCheck.parent, list);
+  }
+
+  return isExcluded;
+}
 
 /**
  * Creates a "standard" mesh from an instanced mesh, by cloning the source mesh and applying transformation data
  */
-const createMeshFromInstancedMesh = function (
+export function createMeshFromInstancedMesh(
   instancedMesh: InstancedMesh,
   newName: string,
-  clonedParent: Nullable<TransformNode>
-) {
+  clonedParent: TransformNode
+): Mesh {
   // first create a clone of the source mesh
   const newMesh = instancedMesh.sourceMesh.clone(newName, clonedParent, true);
+  cloneInternalMetadata(instancedMesh.sourceMesh, newMesh);
   // apply the transformation data, it's important to create clones of the transformations to not touch the original
   // transformation when applying changes (eg: geometry baking)
   newMesh.position = instancedMesh.position.clone();
@@ -33,13 +74,13 @@ const createMeshFromInstancedMesh = function (
   newMesh.setEnabled(instancedMesh.isEnabled(false));
 
   return newMesh;
-};
+}
 
 /**
  * Removes transformation data from the mesh and stores it in the geometry, which is called "baking".
  * Also considers the geometry change from morph targets.
  */
-const bakeGeometryOfMesh = function (mesh: Mesh) {
+export function bakeGeometryOfMesh(mesh: Mesh): void {
   if (!mesh.geometry) {
     // no geometry available, nothing to do
     return;
@@ -79,27 +120,27 @@ const bakeGeometryOfMesh = function (mesh: Mesh) {
 
   // bake the transformation data in the mesh geometry, fortunately there is already a help function from Babylon.js
   mesh.bakeCurrentTransformIntoVertices();
-};
+}
 
 /**
  * Resets transformation to initial state
  */
-const resetTransformation = function (node: TransformNode) {
+export function resetTransformation(node: TransformNode): void {
   node.position = new Vector3(0, 0, 0);
   node.rotation = new Vector3(0, 0, 0);
   node.rotationQuaternion = null;
   node.scaling = new Vector3(1, 1, 1);
-};
+}
 
 /**
  * @param kind morph targets can affect various vertices kinds, whereas "position" is the most common one
  * still other kinds (like normals or tangents) can be affected as well and can be provided on this input
  */
-const _bakeMorphTargetManagerIntoVertices = function (
+function _bakeMorphTargetManagerIntoVertices(
   kind: string,
   morphTargetManager: MorphTargetManager,
   geometry: Geometry
-) {
+): void {
   const origVerticesData = geometry.getVerticesData(kind);
   if (!origVerticesData) {
     // no vertices data for this kind availabe on the mesh geometry
@@ -122,9 +163,9 @@ const _bakeMorphTargetManagerIntoVertices = function (
 
   // apply the updated vertices data
   geometry.setVerticesData(kind, verticesData);
-};
+}
 
-const _getVerticesDataFromMorphTarget = function (kind: string, morphTarget: MorphTarget): Nullable<FloatArray> {
+function _getVerticesDataFromMorphTarget(kind: string, morphTarget: MorphTarget): FloatArray | null {
   switch (kind) {
     case VertexBuffer.PositionKind:
       return morphTarget.getPositions();
@@ -137,6 +178,4 @@ const _getVerticesDataFromMorphTarget = function (kind: string, morphTarget: Mor
   }
 
   return null;
-};
-
-export { createMeshFromInstancedMesh, bakeGeometryOfMesh, resetTransformation };
+}

package/src/internal/metadataHelper.ts

@@ -0,0 +1,63 @@
+import { BaseTexture, Material, Node } from '../index';
+import { cloneDeep } from 'lodash-es';
+
+type MetadataValue = string | number | boolean | undefined;
+type MetadataTarget = Node | Material | BaseTexture;
+type MetadataKeys =
+  // CBN babylon loader
+  | 'deferredMaterial'
+  // material manager
+  | 'materialToBeSet'
+  // GLTF export
+  | 'exportNode'
+  | 'deleteAfterExport'
+  | 'exchangeMaterialWith'
+  // cloning
+  | 'cloneSource'
+  | 'cloneTarget';
+
+// TODO WTT: use generics or some kind of logic that is able to type the metadata according to their key
+/**
+ * Sets certain metadata on the objects INTERNAL metadata storage.
+ * "object._internalMetadata.cbn" is reserved for CBN specific metadata information.
+ * The objects public metadata ("object.metadata") is not affected and should therefore not interfere with metadata
+ * that is used in consumer projects.
+ */
+export function setInternalMetadataValue(object: MetadataTarget, key: MetadataKeys, value: MetadataValue): void {
+  if (!object._internalMetadata) {
+    object._internalMetadata = {};
+  }
+  if (!object._internalMetadata.cbn) {
+    object._internalMetadata.cbn = {};
+  }
+
+  object._internalMetadata.cbn[key] = value;
+}
+
+export function clearInternalMetadataValue(object: MetadataTarget, key: MetadataKeys): void {
+  delete object._internalMetadata?.cbn?.[key];
+}
+
+export function getInternalMetadataValue(object: MetadataTarget, key: MetadataKeys): MetadataValue {
+  return object._internalMetadata?.cbn?.[key];
+}
+
+/**
+ * Creates a deep clone from the source objects internal metadata and assigns it to the target objects metadata.
+ * This is required as Babylon.js only creates shallow clones of the internal metadata, which would be problematic for
+ * our needs.
+ */
+export function cloneInternalMetadata(sourceObject: MetadataTarget, targetObject: MetadataTarget): void {
+  targetObject._internalMetadata = cloneDeep(sourceObject._internalMetadata);
+}
+
+/**
+ * Clones the metadata from one object to another.
+ * CAUTION: this is now the public available "object.metadata" object.
+ * We need this function internally when cloning instanced meshes.
+ */
+export function cloneMetadata(sourceObject: MetadataTarget, targetObject: MetadataTarget): void {
+  const clonedMetadata = cloneDeep(sourceObject.metadata);
+
+  targetObject.metadata = clonedMetadata;
+}