getFirstMatchingChildPrim#

Fully qualified name: isaacsim::foundation::utils::getFirstMatchingChildPrim

std::optional<std::string> isaacsim::foundation::utils::getFirstMatchingChildPrim(
const std::string &path,
std::function<bool(const std::string&)> predicate,
bool includeSelf = false,
std::optional<std::size_t> maxDepth = std::nullopt,
)#

Returns the first prim in the subtree rooted at path for which predicate returns true.

Performs a breadth-first traversal of the default stage. Prims are visited in BFS order; the first one for which predicate returns true is returned immediately and traversal stops.

When includeSelf is false the root prim is skipped and traversal begins with its direct children. When includeSelf is true the root is the first candidate tested.

When maxDepth is set, traversal stops as soon as the current prim’s depth exceeds maxDepth. Because the deque is ordered by depth in BFS order, all remaining items at that point are at the same or greater depth, so the entire search halts immediately.

See also

getAllMatchingChildPrims()

Parameters:
  • path – [in] USD path of the subtree root on the default stage.

  • predicate – [in] Callable invoked with the string path of each visited prim; return true to select that prim.

  • includeSelf – [in] Whether to test path itself before its descendants.

  • maxDepth – [in] Maximum traversal depth relative to path, where path itself is at depth 0 and its direct children at depth 1. std::nullopt means unlimited depth. Note that depth is always counted from path regardless of includeSelf, so maxDepth=0 combined with includeSelf=false visits no prim at all: the direct children the traversal starts from are already at depth 1. Use maxDepth=1 to visit the direct children.

Returns:

The path of the first matching prim, or std::nullopt if no match is found.