@combeenation/3d-viewer 18.2.0 → 18.3.0

package/src/internal/export-helper.ts

@@ -0,0 +1,378 @@
+import {
+  DynamicTexture,
+  FloatArray,
+  Geometry,
+  InstancedMesh,
+  Material,
+  Mesh,
+  MorphTarget,
+  MorphTargetManager,
+  Node,
+  NodeDescription,
+  RenderTargetTexture,
+  TransformNode,
+  Vector3,
+  VertexBuffer,
+  Viewer,
+} from '../index';
+import { getIsScaledDownDevice } from './device-helper';
+import {
+  clearInternalMetadataValue,
+  cloneInternalMetadata,
+  getInternalMetadataValue,
+  setInternalMetadataValue,
+} from './metadata-helper';
+import { nodeMatchesAnyCriteria } from './node-helper';
+
+type ExportPreProcessSettings = {
+  excludeNodes?: NodeDescription[];
+  scaleDownTextures?: boolean;
+};
+type ExportPostProcessSettings = {
+  initialTextureSize?: number;
+};
+
+/**
+ * Prepares scene for exports.
+ * The main task is to bake the transformation data into the vertices, as our current exports (GLB for AR and DXF) don't
+ * work conveniently without it:
+ * - negative signs in scaling values in GLBs lead to erroneous appearance in converted .usdz file
+ * - DXF faces calculation only takes vertices into account
+ */
+export async function exportPreProcess(viewer: Viewer, settings?: ExportPreProcessSettings): Promise<void> {
+  const { excludeNodes, scaleDownTextures } = settings ?? {};
+
+  // pause rendering, since we are altering the active scene, which should not be visible to the user
+  viewer.pauseRendering();
+
+  // exchange textures with scaled down versions (1024 px) if desired
+  // Example AR (GLB) export:
+  // - iOS devices will crash most likely when trying to access AR endpoints with such files
+  // - file size will be reduced, which leads to faster loading times
+  // - textures > 1024 px shouldn't make a difference on mobiles anyway
+  // we don't have to rescale anything if are already on a downscaled device, since the textures are already <= 1024
+  // also we have to be very cautios with copying textures on these devices, since we are potentially very limited
+  // with the available memory
+  const isScaledDownDevice = getIsScaledDownDevice(viewer.viewerSettings.limitTextureSize);
+  if (scaleDownTextures && !isScaledDownDevice) {
+    // the idea is to re-create all textures with a smaller texture size
+    // we have to exchange all materials for this to work
+    viewer.engine.clearInternalTexturesCache();
+    viewer.engine.getCaps().maxTextureSize = 1024;
+
+    viewer.scene.materials.forEach(material => _exchangePBRMaterial(material));
+  }
+
+  // create clones of each node (recursively), optionally exchange with cloned materials and mark these nodes for the
+  // export
+  viewer.scene.rootNodes.forEach(rootNode => _prepareNodeForExport(viewer, rootNode, null, excludeNodes));
+
+  const nodesForExport = _getNodesMarkedForExport(viewer);
+  // bake transformation of all meshes, so that no negative scalings are left
+  // it's important that this is done AFTER instanced meshes have been converted (`_prepareNodeForExport`)
+  nodesForExport.forEach(node => {
+    if (node instanceof Mesh) _bakeGeometryOfMesh(node);
+  });
+
+  // reset transformation of all "TransformNodes", as transform nodes are not considered by the `_bakeGeometryOfMesh`
+  // function, still their transformation data has to be reset to eliminated negative scalings and to make the baking of
+  // child meshes work
+  // it's important that this is done AFTER all geometries have been baked
+  nodesForExport.forEach(node => {
+    _resetTransformation(node);
+    // recompute world matrix immediately after adapting transformation
+    node.computeWorldMatrix(true);
+  });
+}
+
+/**
+ * Cleans up scene after export
+ */
+export async function exportPostProcess(viewer: Viewer, settings?: ExportPostProcessSettings): Promise<void> {
+  const { initialTextureSize } = settings ?? {};
+
+  // dispose all nodes, materials and textures that have only been created for the export
+  viewer.scene.rootNodes
+    .filter(rootNode => getInternalMetadataValue(rootNode, 'deleteAfterExport'))
+    .forEach(rootNode => rootNode.dispose());
+
+  viewer.scene.materials
+    .filter(material => getInternalMetadataValue(material, 'deleteAfterExport'))
+    .forEach(material => material.dispose(false, false));
+  // clean up temporary material exchange key for the rest of materials
+  viewer.scene.materials.forEach(material => clearInternalMetadataValue(material, 'exchangeMaterialWith'));
+
+  viewer.scene.textures
+    .filter(texture => getInternalMetadataValue(texture, 'deleteAfterExport'))
+    .forEach(texture => texture.dispose());
+
+  if (initialTextureSize) {
+    // reset texture size, only required if `scaleDownTextures` had been set in pre process
+    viewer.engine.getCaps().maxTextureSize = initialTextureSize;
+  }
+
+  viewer.resumeRendering();
+}
+
+/**
+ * Checks if a node should be available in the export
+ */
+export function isExportableTransformNode(node: Node, excludeNodes?: NodeDescription[]): node is TransformNode {
+  if (!(node instanceof TransformNode)) {
+    return false;
+  }
+
+  // maybe add some other criterias like "hasInfiniteDistance" and "isGeneratedBackgroundMesh" here as well
+  const isExcluded = nodeMatchesAnyCriteria(node, {
+    isInList: excludeNodes,
+    isDisabled: true,
+    isHtmlAnchorMesh: true,
+  });
+
+  return !isExcluded;
+}
+
+/**
+ * Triggers a browser download from a given object URL or data URI./
+ * The file will be saved with the specified file name.
+ */
+export function downloadFile(url: string, fileName: string): void {
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = fileName;
+  document.body.appendChild(link);
+  link.click();
+  document.body.removeChild(link);
+}
+
+/**
+ * Add extension if not already set
+ */
+export function normalizeFileName(fileName: string | undefined, extension: string, defaultFileName?: string): string {
+  const extensionWithDot = '.' + extension;
+  const resFileName = fileName ?? defaultFileName ?? 'default';
+
+  return resFileName.endsWith(extensionWithDot) ? resFileName : resFileName + extensionWithDot;
+}
+
+/**
+ * Creates a clone of the material which should be used for the export.
+ * This is mostly required for recreating textures with lower sizes.
+ * CAUTION: Material exchanging is not supported for materials that contain certain texture types:
+ * - Dynamic textures (Paintables): Cloning dynamic textures doesn't clone the canvas context
+ *   => so the clone is just empty
+ * - Render target textures: Disposing the clone will leave the scene in a "not ready" state
+ *   => this scenario is not fully analyzed yet, but it's not really worth the effort right now, since this kind of
+ *      of texture is not really used ATM
+ */
+function _exchangePBRMaterial(material: Material): void {
+  const baseTextures = material.getActiveTextures();
+  const hasDynamicTextures = baseTextures.some(texture => texture instanceof DynamicTexture);
+  const hasRenderTargetTextures = baseTextures.some(texture => texture instanceof RenderTargetTexture);
+  if (hasDynamicTextures || hasRenderTargetTextures) {
+    const textureTypesString = [
+      hasDynamicTextures ? 'Dynamic Textures' : '',
+      hasRenderTargetTextures ? 'Render Target Textures' : '',
+    ]
+      .filter(Boolean)
+      .join();
+    console.warn(
+      `Couldn't exchange material "${material.name}" in export, as it contains unsupported texture type(s) (${textureTypesString}). The export will still work, but the textures of this material will keep their original size.`
+    );
+
+    return;
+  }
+
+  const newName = `${material.name}_clone`;
+  const clonedMaterial = material.clone(newName)!;
+  cloneInternalMetadata(material, clonedMaterial);
+  const clonedTextures = clonedMaterial.getActiveTextures();
+
+  // mark all exported textures, so that they will be deleted after the export
+  clonedTextures.forEach(texture => setInternalMetadataValue(texture, 'deleteAfterExport', true));
+
+  setInternalMetadataValue(material, 'exchangeMaterialWith', clonedMaterial.uniqueId);
+  setInternalMetadataValue(clonedMaterial, 'deleteAfterExport', true);
+}
+
+/**
+ * Creates a clone of the node which should be used for the export.
+ * Also switches to the cloned material if required.
+ */
+function _prepareNodeForExport(
+  viewer: Viewer,
+  node: Node,
+  clonedParent: TransformNode | null,
+  excludeNodes?: NodeDescription[]
+): void {
+  if (!isExportableTransformNode(node, excludeNodes)) {
+    return;
+  }
+
+  // clone original node and create unique name (via uniqueId) for the export
+  const clonedNodeName = `${node.name}_${node.uniqueId}`;
+  const clonedNode =
+    node instanceof InstancedMesh
+      ? _createMeshFromInstancedMesh(node, clonedNodeName, clonedParent)
+      : node.clone(clonedNodeName, clonedParent, true)!;
+  cloneInternalMetadata(node, clonedNode);
+
+  // exchange material
+  if (clonedNode instanceof Mesh) {
+    const exchangeWithMaterial =
+      clonedNode.material && getInternalMetadataValue(clonedNode.material, 'exchangeMaterialWith');
+    if (exchangeWithMaterial) {
+      clonedNode.material = viewer.scene.getMaterialByUniqueID(exchangeWithMaterial as number);
+    }
+  }
+
+  // signalize that this is a cloned node
+  setInternalMetadataValue(clonedNode, 'exportNode', true);
+  setInternalMetadataValue(clonedNode, 'deleteAfterExport', true);
+
+  // handle children
+  const childs = node.getChildTransformNodes(true);
+  childs.forEach(child => _prepareNodeForExport(viewer, child, clonedNode, excludeNodes));
+}
+
+/**
+ * Help function for receiving all nodes that are marked for the export
+ */
+function _getNodesMarkedForExport(viewer: Viewer): TransformNode[] {
+  const nodes = [...viewer.scene.meshes, ...viewer.scene.transformNodes];
+
+  const filteredNodes = nodes.filter(node => getInternalMetadataValue(node, 'exportNode'));
+  return filteredNodes;
+}
+
+/**
+ * Creates a "standard" mesh from an instanced mesh, by cloning the source mesh and applying transformation data
+ */
+function _createMeshFromInstancedMesh(
+  instancedMesh: InstancedMesh,
+  newName: string,
+  clonedParent: TransformNode | null
+): 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();
+  newMesh.rotation = instancedMesh.rotation.clone();
+  newMesh.scaling = instancedMesh.scaling.clone();
+
+  // rotation quaternion is optional
+  if (instancedMesh.rotationQuaternion) {
+    newMesh.rotationQuaternion = instancedMesh.rotationQuaternion.clone();
+  }
+
+  // also sync the enabled state from the original instanced mesh
+  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.
+ */
+function _bakeGeometryOfMesh(mesh: Mesh): void {
+  if (!mesh.geometry) {
+    // no geometry available, nothing to do
+    return;
+  }
+
+  // geometries can be shared across multiple meshes, first make them unique to avoid side-effects
+  mesh.makeGeometryUnique();
+
+  // Babylon.js already provides a function for baking the current skeleton changes into the geometry
+  if (mesh.skeleton) {
+    mesh.applySkeleton(mesh.skeleton);
+    mesh.skeleton = null;
+  }
+
+  // NOTE: in difference to skeletons and transformations there is no baking function for morph targets (yet)
+  // however another approach could be to re-apply the position and normals data, as there are nice functions for it
+  // - `getPositionData(applySkeleton: boolean = false, applyMorph: boolean = false)`
+  // - `getNormalsData(applySkeleton: boolean = false, applyMorph: boolean = false)`
+  // you can decide if skeletons and morph targets can be added, which is exactly what we want
+  // I'm still hesitant to use it because "tangent" and "UV" kinds are not supported, whereas I'm not sure if it's
+  // required
+  // => try it out when there is enough time for detailed regression tests!
+  const morphTargetManager = mesh.morphTargetManager;
+  const geometry = mesh.geometry;
+
+  if (morphTargetManager?.numTargets) {
+    // apply morph target vertices data to mesh geometry
+    // mostly only the "PositionKind" is implemented
+    _bakeMorphTargetManagerIntoVertices(VertexBuffer.PositionKind, morphTargetManager, geometry);
+    _bakeMorphTargetManagerIntoVertices(VertexBuffer.NormalKind, morphTargetManager, geometry);
+    _bakeMorphTargetManagerIntoVertices(VertexBuffer.TangentKind, morphTargetManager, geometry);
+    _bakeMorphTargetManagerIntoVertices(VertexBuffer.UVKind, morphTargetManager, geometry);
+
+    // remove morph target manager with all it's morph targets
+    mesh.morphTargetManager = null;
+  }
+
+  // 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
+ */
+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
+ */
+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
+    return;
+  }
+
+  let verticesData = [...origVerticesData];
+  for (let i = 0; i < morphTargetManager.numTargets; i++) {
+    const target = morphTargetManager.getTarget(i);
+    const targetVerticesData = _getVerticesDataFromMorphTarget(kind, target);
+    if (targetVerticesData) {
+      // vertices data of this kind are implemented on the morph target
+      // add the influence of this morph target to the vertices data
+      // formula is taken from: https://doc.babylonjs.com/features/featuresDeepDive/mesh/morphTargets#basics
+      verticesData = verticesData.map(
+        (oldVal, idx) => oldVal + (targetVerticesData[idx] - origVerticesData[idx]) * target.influence
+      );
+    }
+  }
+
+  // apply the updated vertices data
+  geometry.setVerticesData(kind, verticesData);
+}
+
+function _getVerticesDataFromMorphTarget(kind: string, morphTarget: MorphTarget): FloatArray | null {
+  switch (kind) {
+    case VertexBuffer.PositionKind:
+      return morphTarget.getPositions();
+    case VertexBuffer.NormalKind:
+      return morphTarget.getNormals();
+    case VertexBuffer.TangentKind:
+      return morphTarget.getTangents();
+    case VertexBuffer.UVKind:
+      return morphTarget.getUVs();
+  }
+
+  return null;
+}

package/src/internal/node-helper.ts

@@ -59,8 +59,8 @@ export function nodeMatchesAnyCriteria(nodeToCheck: TransformNode, criteria: Nod
     matchesIsGeneratedBackgroundMesh ||
     matchesIsHtmlAnchorMesh ||
     matchesIsDimensionLine;
-  // consider parent as well, BUT ONLY for list and disabled state, as the other criterias have nothing to do with a
-  // child-parent relation
+  // consider parent as well, BUT ONLY for list, disabled state and background mesh, as the other criterias have nothing
+  // to do with a child-parent relation
   if (!matchesAnyCriteria && nodeToCheck.parent instanceof TransformNode) {
     matchesAnyCriteria = nodeMatchesAnyCriteria(nodeToCheck.parent, {
       isInList,

package/src/manager/camera-manager.ts

@@ -11,6 +11,7 @@ import {
   ViewerErrorIds,
   ViewerEvent,
 } from '../index';
+import { downloadFile } from '../internal/export-helper';
 import { nodeMatchesAnyCriteria } from '../internal/node-helper';
 import { createScreenshotCanvas, trimCanvas } from '../internal/screenshot-helper';
 
@@ -401,12 +402,7 @@ export class CameraManager {
     if (fileName) {
       // rebuild Babylon.js default behaviour: if a file name is given, download the screenshot instead of returning the
       // data string
-      const link = document.createElement('a');
-      link.href = imageStr;
-      link.download = fileName;
-      document.body.appendChild(link);
-      link.click();
-      document.body.removeChild(link);
+      downloadFile(imageStr3d, fileName);
 
       return '';
     } else {

package/src/manager/dxf-export-manager.ts

@@ -0,0 +1,123 @@
+import { NodeDescription, Vector3, VertexBuffer, Viewer } from '../index';
+import { downloadFile, exportPostProcess, exportPreProcess, normalizeFileName } from '../internal/export-helper';
+import { getInternalMetadataValue } from '../internal/metadata-helper';
+import { nodeMatchesAnyCriteria } from '../internal/node-helper';
+import DRAWING, { Unit } from 'dxf-writer';
+
+export type DxfUnit = Unit;
+
+export type DxfExportSettings = {
+  fileName?: string;
+  /** List of nodes that should be excluded from the DXF export */
+  excludeNodes?: NodeDescription[];
+  /**
+   * Unit of the 3d model.\
+   * If a unit is set, CAD tools are able to convert the values from the DXF into the configured unit of the CAD tool.
+   */
+  unit?: DxfUnit;
+};
+
+/**
+ * Manager for creating DXF exports of the current viewer scene
+ */
+export class DxfExportManager {
+  /** @internal */
+  public constructor(protected viewer: Viewer) {}
+
+  /**
+   * Returns DXF export as `File` for further processing. (e.g upload as Cfgn file)
+   */
+  public async createDxf(settings?: DxfExportSettings): Promise<File> {
+    const normalizedFileName = normalizeFileName(settings?.fileName, 'dxf', 'dxf-export');
+
+    const dxfBlob = await this._createDxfBlob(settings);
+    const dxfFile = new File([dxfBlob], normalizedFileName, { type: 'application/dxf' });
+
+    return dxfFile;
+  }
+
+  /**
+   * Creates DXF export and downloads the resulting file right away
+   */
+  public async downloadDxf(settings?: DxfExportSettings): Promise<void> {
+    const normalizedFileName = normalizeFileName(settings?.fileName, 'dxf', 'dxf-export');
+
+    const dxfBlob = await this._createDxfBlob(settings);
+
+    const url = URL.createObjectURL(dxfBlob);
+    downloadFile(url, normalizedFileName);
+    URL.revokeObjectURL(url);
+  }
+
+  /**
+   * Help function for creating a blob with the DXF string, as this is needed for both public interface functions
+   * (`exportDxf` & `exportDxfToFile`)
+   */
+  protected async _createDxfBlob(settings?: DxfExportSettings): Promise<Blob> {
+    // Transformation baking pre process is required for DXF exports, as we take the plain vertex information for the
+    // DXF conversion, therefore the vertices need to be located in world already
+    await exportPreProcess(this.viewer, { excludeNodes: settings?.excludeNodes });
+    const dxfString = this._createDxf(settings?.unit);
+    await exportPostProcess(this.viewer);
+
+    const dxfBlob = new Blob([dxfString], { type: 'application/dxf' });
+    return dxfBlob;
+  }
+
+  /**
+   * DXF creation process.\
+   * We go through all vertices of all meshes and create DXF 3d faces accordingly.
+   */
+  protected _createDxf(unit?: DxfUnit): string {
+    const DXF = new DRAWING();
+    if (unit) {
+      DXF.setUnits(unit);
+    }
+
+    const meshesToExport = this.viewer.scene.meshes.filter(
+      mesh =>
+        getInternalMetadataValue(mesh, 'exportNode') &&
+        // NOTE: can't add this criteria in pre export process, as pre export process works recursively and childs of
+        // transforms nodes or meshes without geometry can still have geometries and therefore be valid for the export
+        !nodeMatchesAnyCriteria(mesh, { hasInvalidBoundingInfo: true })
+    );
+
+    meshesToExport.forEach(mesh => {
+      const positions = mesh.getVerticesData(VertexBuffer.PositionKind);
+      const indices = mesh.getIndices();
+      if (!positions || !indices) {
+        console.warn(`Can't create DXF export of mesh "${mesh.name}", as there is no vertex data available`);
+        return;
+      }
+
+      for (let i = 0; i < indices.length; i += 3) {
+        // A face always consists of 3 vertices.
+        // First we need to get the indizes of the vertices.
+        const idx1 = indices[i];
+        const idx2 = indices[i + 1];
+        const idx3 = indices[i + 2];
+
+        // Now get the x, y, z data of the associated index.
+        // One index stores 3 vertices, thats why the index is multiplied with 3 before accessing the actual vertex
+        // position.
+        // > and z components have dedicated offsets 1 and 2.
+        // ===============
+        // Important NOTE:
+        // ===============
+        // DXF is right-handed, according to tests in AutoDesk it seems like y and z components are just switched.
+        // So we use offset 2 for y and offset 1 for z.
+        const p1 = new Vector3(positions[idx1 * 3], positions[idx1 * 3 + 2], positions[idx1 * 3 + 1]);
+        const p2 = new Vector3(positions[idx2 * 3], positions[idx2 * 3 + 2], positions[idx2 * 3 + 1]);
+        const p3 = new Vector3(positions[idx3 * 3], positions[idx3 * 3 + 2], positions[idx3 * 3 + 1]);
+
+        // Add a 3D face to the DXF (3DFACE entity).
+        // The library works with 4 points per face, but we only have 3.
+        // Using the last point 3 times is fine though.
+        DXF.drawFace(p1.x, p1.y, p1.z, p2.x, p2.y, p2.z, p3.x, p3.y, p3.z, p3.x, p3.y, p3.z);
+      }
+    });
+
+    const dxfString = DXF.toDxfString();
+    return dxfString;
+  }
+}