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

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}.\
+ * If property is omitted, the dedicated filter passes.
+ *
+ * @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) {}
@@ -99,6 +130,41 @@ export class ViewerUtils {
     return node;
   }
 
+  /**
+   * 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
+   */
+  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 => this._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;
+    }
+
+    const matchesCriteria = this._matchesFindNodeCriteria(parent, criteria);
+    if (matchesCriteria) {
+      return parent as T;
+    } else {
+      return this.findParentNode(parent, criteria);
+    }
+  }
+
   /**
    * @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
@@ -146,4 +212,22 @@ export class ViewerUtils {
 
     return null;
   }
+
+  protected _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 || this._matchesMetadata(node.metadata, metadataObject);
+    const typeFits = !type || node instanceof type;
+
+    return nodeNameFits && tagNameFits && metadataFits && typeFits;
+  }
+
+  protected _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);
+  }
 }