@combeenation/3d-viewer 20.0.0-alpha2 → 20.0.0

package/src/manager/camera-manager.ts

@@ -24,17 +24,47 @@ export type CameraPosition = {
 };
 
 export type AutofocusSettings = {
-  /** Can be used to customize the margins shown around the 3d model. Defaults to 1. */
+  /**
+   * Can be used to customize the margins shown around the 3d model.\
+   * Default: 1
+   */
   radiusFactor?: number;
+  /** Default: true */
+  adjustLowerRadiusLimit?: boolean;
+  /** Default: true */
+  adjustMinZ?: boolean;
+  /** Default: true */
   adjustWheelPrecision?: boolean;
+  /** Default: true */
   adjustPanningSensibility?: boolean;
+  /** Default: true */
   adjustPinchPrecision?: boolean;
+  /**
+   * `true:` uses `alpha` from input or default value (45°), `false:` keeps current alpha from camera\
+   * Default: true
+   */
+  adjustAlpha?: boolean;
+  /**
+   * `true:` uses `beta` from input or default value (75°), `false:` keeps current beta from camera\
+   * Default: true
+   */
+  adjustBeta?: boolean;
+  /**
+   * `true:` uses calculated radius to fit scene bounding sphere, `false:` keeps current radius from camera\
+   * Default: true
+   */
+  adjustRadius?: boolean;
   /** Desired horizontal camera angle, this won't be overwritten by the autofocus function */
   alpha?: number;
   /** Desired vertical camera angle, this won't be overwritten by the autofocus function */
   beta?: number;
   /** Optional list of nodes to be excluded from camera distance calculation for autofocusing */
   excludeNodes?: NodeDescription[];
+  /**
+   * Defines if HTML anchors should be considered for the autofocus camera distance calculation.\
+   * Default: `true`
+   */
+  excludeHtmlAnchors?: boolean;
   durationMs?: number;
 };
 
@@ -152,6 +182,20 @@ export class CameraManager {
    * Focuses the camera to see every visible mesh in scene and tries to optimize wheel precision and panning
    */
   public async autofocusActiveCamera(settings?: AutofocusSettings): Promise<void> {
+    const {
+      adjustLowerRadiusLimit,
+      adjustMinZ,
+      adjustWheelPrecision,
+      adjustPanningSensibility,
+      adjustPinchPrecision,
+      adjustAlpha,
+      adjustBeta,
+      adjustRadius,
+      excludeNodes,
+      excludeHtmlAnchors,
+      durationMs,
+    } = settings ?? {};
+
     const activeCamera = this.viewer.scene.activeCamera;
 
     if (!(activeCamera instanceof ArcRotateCamera)) {
@@ -162,42 +206,49 @@ export class CameraManager {
     }
 
     // get bounding box of all visible meshes, this is the base for the autofocus algorithm
-    const boundingInfo = this.viewer.sceneManager.calculateBoundingInfo(settings?.excludeNodes);
+    const boundingInfo = this.viewer.sceneManager.calculateBoundingInfo({ excludeNodes, excludeHtmlAnchors });
     // optionally show bounding sphere for debugging purpose
     this.viewer.eventManager.fireEvent(ViewerEvent.AutofocusStart, boundingInfo.boundingSphere);
 
     const distance = this._getAutofocusZoomingDistance(boundingInfo.boundingSphere, activeCamera);
-    const radius = boundingInfo.boundingSphere.radius;
-    const center = boundingInfo.boundingSphere.center;
+    const bBoxRadius = boundingInfo.boundingSphere.radius;
+    const bBoxCenter = boundingInfo.boundingSphere.center;
 
     // set lower radius limit on edge of bounding sphere to make sure that we can't dive into the meshes
-    activeCamera.lowerRadiusLimit = radius;
+    if (adjustLowerRadiusLimit !== false) {
+      activeCamera.lowerRadiusLimit = bBoxRadius;
+    }
 
     // additional settings
     // constants for division are taken directly from Babylon.js repository
-    activeCamera.minZ = Math.min(radius / CameraManager._AUTOFOCUS_CONSTANTS.minZ, 1);
-    if (settings?.adjustWheelPrecision !== false) {
-      activeCamera.wheelPrecision = CameraManager._AUTOFOCUS_CONSTANTS.wheelPrecision / radius;
+    if (adjustMinZ !== false) {
+      activeCamera.minZ = Math.min(bBoxRadius / CameraManager._AUTOFOCUS_CONSTANTS.minZ, 1);
     }
-    if (settings?.adjustPanningSensibility !== false) {
-      activeCamera.panningSensibility = CameraManager._AUTOFOCUS_CONSTANTS.panningSensibility / radius;
+    if (adjustWheelPrecision !== false) {
+      activeCamera.wheelPrecision = CameraManager._AUTOFOCUS_CONSTANTS.wheelPrecision / bBoxRadius;
     }
-    if (settings?.adjustPinchPrecision !== false) {
-      activeCamera.pinchPrecision = CameraManager._AUTOFOCUS_CONSTANTS.pinchPrecision / radius;
+    if (adjustPanningSensibility !== false) {
+      activeCamera.panningSensibility = CameraManager._AUTOFOCUS_CONSTANTS.panningSensibility / bBoxRadius;
+    }
+    if (adjustPinchPrecision !== false) {
+      activeCamera.pinchPrecision = CameraManager._AUTOFOCUS_CONSTANTS.pinchPrecision / bBoxRadius;
     }
 
-    const radiusFactor = settings?.radiusFactor ?? CameraManager._DEFAULT_AUTOFOCUS_RADIUS_FACTOR;
-    const alpha = settings?.alpha ?? CameraManager.DEFAULT_CAMERA_POSITION.alpha;
-    const beta = settings?.beta ?? CameraManager.DEFAULT_CAMERA_POSITION.beta;
+    const adjustedAlpha = settings?.alpha ?? CameraManager.DEFAULT_CAMERA_POSITION.alpha;
+    const alpha = adjustAlpha !== false ? adjustedAlpha : activeCamera.alpha;
+    const adjustedBeta = settings?.beta ?? CameraManager.DEFAULT_CAMERA_POSITION.beta;
+    const beta = adjustBeta !== false ? adjustedBeta : activeCamera.beta;
+    const adjustedRadiusFactor = settings?.radiusFactor ?? CameraManager._DEFAULT_AUTOFOCUS_RADIUS_FACTOR;
+    const radius = adjustRadius !== false ? distance * adjustedRadiusFactor : activeCamera.radius;
 
     const newCameraPosition: CameraPosition = {
-      alpha: alpha,
-      beta: beta,
-      radius: distance * radiusFactor,
-      target: center,
+      alpha,
+      beta,
+      radius,
+      target: bBoxCenter,
     };
 
-    await this.moveActiveCameraTo(newCameraPosition, settings?.durationMs);
+    await this.moveActiveCameraTo(newCameraPosition, durationMs);
   }
 
   /**
@@ -314,7 +365,12 @@ export class CameraManager {
     const screenshotCam = this.viewer.scene.activeCamera?.clone(
       CameraManager._SCREENSHOT_CAMERA_NAME
     ) as ArcRotateCamera;
-    const boundingInfo = autofocusScene ? this.viewer.sceneManager.calculateBoundingInfo(excludeNodes) : undefined;
+    const boundingInfo = autofocusScene
+      ? this.viewer.sceneManager.calculateBoundingInfo({
+          excludeNodes,
+          excludeHtmlAnchors: excludeHtmlAnchorGroups === true,
+        })
+      : undefined;
 
     if (alpha !== undefined) {
       screenshotCam.alpha = alpha;

package/src/manager/scene-manager.ts

@@ -83,6 +83,16 @@ export type UpdateShadowsSettings = {
   excludeReceiverNodes?: NodeDescription[];
 };
 
+export type CalculateBoundingInfoSettings = {
+  /** Optional list of nodes to be excluded from bounding info calculation */
+  excludeNodes?: NodeDescription[];
+  /**
+   * Defines if HTML anchors should be considered for the bounding info calculation.\
+   * Default: `true`
+   */
+  excludeHtmlAnchors?: boolean;
+};
+
 /**
  * Additional scene settings, which are not available in a basic `AssetContainer`.
  * !!! IMPORTANT when adding a new property !!!
@@ -282,7 +292,9 @@ export class SceneManager {
    * - do not have a material of type "BackgroundMaterial"
    * - do not have an infinite distance (like sky boxes)
    */
-  public calculateBoundingInfo(excludeNodes?: NodeDescription[]): BoundingInfo {
+  public calculateBoundingInfo(settings?: CalculateBoundingInfoSettings): BoundingInfo {
+    const { excludeNodes, excludeHtmlAnchors } = settings ?? {};
+
     // CB-6062: workaround for BoundingBox not respecting render loop
     this.viewer.scene.render();
 
@@ -295,7 +307,7 @@ export class SceneManager {
           hasInvalidBoundingInfo: true,
           hasInfiniteDistance: true,
           isGeneratedBackgroundMesh: true,
-          isHtmlAnchorMesh: true,
+          isHtmlAnchorMesh: excludeHtmlAnchors !== false,
         });
 
         return !isExcluded;
@@ -323,7 +335,7 @@ export class SceneManager {
    * plane mesh can be used as well.
    */
   public updateGround(settings?: UpdateGroundSettings): void {
-    const bboxInfo = this.calculateBoundingInfo(settings?.excludeNodes);
+    const bboxInfo = this.calculateBoundingInfo({ excludeNodes: settings?.excludeNodes });
 
     const groundMesh = settings?.groundMesh ?? this.viewer.scene.getMeshByName(SceneManager._DEFAULT_GROUND_PLANE_NAME);
     if (!groundMesh) {

package/src/utils/viewer-utils.ts

@@ -4,6 +4,8 @@ import {
   Mesh,
   MorphTarget,
   MorphTargetManager,
+  Node,
+  Tags,
   TransformNode,
   Vector3,
   VertexBuffer,
@@ -13,6 +15,7 @@ import {
 export type BakeGeometrySettings = {
   keepTransformation?: boolean;
 };
+
 export type CreateTransformNodeSettings = {
   parentNode?: TransformNode;
   position?: Vector3;
@@ -20,6 +23,34 @@ export type CreateTransformNodeSettings = {
   scaling?: Vector3;
 };
 
+/**
+ * Expected metadata structure for find node functions {@link ViewerUtils.findChildNodes} and
+ * {@link ViewerUtils.findParentNode}
+ */
+export type MetadataObject = Record<string, unknown>;
+
+/**
+ * Contains all constructor that derive from `Node`, e.g. `TransformNode`, `Mesh`
+ */
+export type DerivedNodeType<T extends Node> = new (...args: any[]) => T;
+
+/**
+ * Criteria object for find node functions {@link ViewerUtils.findChildNodes} and {@link ViewerUtils.findParentNode}.\
+ * All given properties must match for the criteria to pass.
+ *
+ * @param nodeName has to match exactly
+ * @param tagName uses algorithm of `Tags.MatchesQuery`, in most cases this is just an exact string match check
+ * @param metadataObject has to be an object, filter passes if all property values of the given input object match the
+ *                       checked node
+ * @param type nodes type has to match (e.g. Mesh)
+ */
+export type FindNodeCriteria<T extends Node> = {
+  nodeName?: string;
+  tagName?: string;
+  metadataObject?: MetadataObject;
+  type?: DerivedNodeType<T>;
+};
+
 export class ViewerUtils {
   /** @internal */
   public constructor(protected viewer: Viewer) {}
@@ -63,10 +94,10 @@ export class ViewerUtils {
     if (morphTargetManager?.numTargets) {
       // apply morph target vertices data to mesh geometry
       // mostly only the "PositionKind" is implemented
-      this._bakeMorphTargetManagerIntoVertices(VertexBuffer.PositionKind, morphTargetManager, geometry);
-      this._bakeMorphTargetManagerIntoVertices(VertexBuffer.NormalKind, morphTargetManager, geometry);
-      this._bakeMorphTargetManagerIntoVertices(VertexBuffer.TangentKind, morphTargetManager, geometry);
-      this._bakeMorphTargetManagerIntoVertices(VertexBuffer.UVKind, morphTargetManager, geometry);
+      _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;
@@ -100,50 +131,103 @@ export class ViewerUtils {
   }
 
   /**
-   * @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
+   * Finds all child nodes (TransformNodes, Meshes, but also Lights, Cameras, etc...) that match a given criteria.
+   *
+   * @param node If left empty, all nodes of the scene are considered
+   * @param criteria If left empty, all child nodes are returned
    */
-  protected _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;
+  public findChildNodes<T extends Node>(node?: Node, criteria?: FindNodeCriteria<T>): T[] {
+    const allNodes = node ? node.getChildren(undefined, false) : [...this.viewer.scene.getNodes()];
+
+    if (!criteria) return allNodes as T[];
+
+    const foundNodes = allNodes.filter(node => _matchesFindNodeCriteria(node, criteria));
+    return foundNodes as T[];
+  }
+
+  /**
+   * Finds nearest node that matches a given criteria.\
+   * Returns `undefined` if no node could be found.
+   */
+  public findParentNode<T extends Node>(node: Node, criteria?: FindNodeCriteria<T>): T | undefined {
+    const parent = node.parent;
+    if (!parent) {
+      return undefined;
+    } else if (!criteria) {
+      return parent as T;
     }
 
-    let verticesData = [...origVerticesData];
-    for (let i = 0; i < morphTargetManager.numTargets; i++) {
-      const target = morphTargetManager.getTarget(i);
-      const targetVerticesData = this._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
-        );
-      }
+    const matchesCriteria = _matchesFindNodeCriteria(parent, criteria);
+    if (matchesCriteria) {
+      return parent as T;
+    } else {
+      return this.findParentNode(parent, criteria);
     }
+  }
+}
 
-    // apply the updated vertices data
-    geometry.setVerticesData(kind, verticesData);
+/**
+ * @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;
   }
 
-  protected _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();
+  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);
+}
 
-    return null;
+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;
+}
+
+function _matchesFindNodeCriteria<T extends Node>(node: Node, criteria?: FindNodeCriteria<T>): boolean {
+  if (!criteria) return true;
+
+  const { nodeName, tagName, metadataObject, type } = criteria;
+  const nodeNameFits = !nodeName || node.name === nodeName;
+  const tagNameFits = !tagName || Tags.MatchesQuery(node, tagName);
+  const metadataFits = !metadataObject || _matchesMetadata(node.metadata, metadataObject);
+  const typeFits = !type || node instanceof type;
+
+  return nodeNameFits && tagNameFits && metadataFits && typeFits;
+}
+
+function _matchesMetadata(metadata: unknown, filter: MetadataObject): boolean {
+  if (!metadata || typeof metadata !== 'object') return false;
+
+  return Object.entries(filter).every(([key, value]) => (metadata as MetadataObject)[key] === value);
 }