EIC code displayed by LXR master/​include/​opencascade/​BRepGraph_ChildExplorer.hxx	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2026-09-28 09:19:34

 // Copyright (c) 2026 OPEN CASCADE SAS
 //
 // This file is part of Open CASCADE Technology software library.
 //
 // This library is free software; you can redistribute it and/or modify it under
 // the terms of the GNU Lesser General Public License version 2.1 as published
 // by the Free Software Foundation, with special exception defined in the file
 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
 // distribution for complete text of the license and disclaimer of any warranty.
 //
 // Alternatively, this file may be used under the terms of Open CASCADE
 // commercial license or contractual agreement.
 
 #ifndef _BRepGraph_ChildExplorer_HeaderFile
 #define _BRepGraph_ChildExplorer_HeaderFile
 
 #include <BRepGraph.hxx>
 #include <BRepGraphInc_Definition.hxx>
 #include <BRepGraphInc_Instance.hxx>
 #include <BRepGraphInc_Reference.hxx>
 #include <BRepGraph_UsagePath.hxx>
 #include <NCollection_ForwardRange.hxx>
 #include <NCollection_LocalArray.hxx>
 #include <TopAbs_Orientation.hxx>
 #include <TopLoc_Location.hxx>
 
 #include <optional>
 
 //! @brief Stack-based lazy downward hierarchy walker for BRepGraph with inline
 //! location/orientation accumulation.
 //! @see BRepGraph class comment "Iterator guide" for choosing between iterator types.
 //!
 //! Walks the graph hierarchy from a root node down to entities of a target kind,
 //! yielding one occurrence at a time via a depth-first stack. Location and
 //! orientation are composed incrementally during the walk, making
 //! Current().Location and Current().Orientation O(1) per call.
 //!
 //! The traversal follows the actual graph structure transparently - every node
 //! kind is visited as a distinct entity (no hidden collapses):
 //!   Compound -> children,  CompSolid -> Solids,  Solid -> Shells,
 //!   Shell -> Faces,  Face -> Wires (+direct Vertices),  Wire -> CoEdges,
 //!   CoEdge -> Edge,  Edge -> Vertices,
 //!   Product -> Occurrences, Occurrence -> Product/topology-root.
 //!
 //! Unlike flat definition traversal by typed ids, BRepGraph_ChildExplorer visits
 //! each occurrence. If Edge[5] is reachable through Face[0] and Face[1],
 //! it is visited twice with different accumulated transforms.
 //!
 //! ## Traversal modes
 //! - **Recursive**: depth-first walk through the full subgraph.
 //!   Without target kind, all descendant nodes are emitted.
 //!   With target kind, only matching nodes are emitted but intermediate
 //!   levels are traversed to reach them.
 //! - **DirectChildren**: yields only the immediate children of the root.
 //!   No descent into grandchildren.  With target kind, only children
 //!   matching the kind are returned.
 class BRepGraph_ChildExplorer
 {
 public:
   DEFINE_STANDARD_ALLOC
 
   //! Relationship kind between Current() and CurrentParent().
   enum class LinkKind
   {
     None,       //!< No current incoming link (e.g. root/self match).
     Reference,  //!< Current() is reached through a parent-owned RefId.
     Structural, //!< Current() is reached through a structural non-ref link.
   };
 
   //! Downward traversal strategy.
   enum class TraversalMode
   {
     Recursive,      //!< Depth-first walk through the full subgraph.
     DirectChildren, //!< Yields only the immediate children of the root.
   };
 
   //! Consolidated configuration for the explorer.
   //!
   //! The `Config`-based constructor is the preferred idiom: new options can be
   //! added as fields without additional constructor overloads.
   //!
   //! @code
   //!   BRepGraph_ChildExplorer::Config aConfig;
   //!   aConfig.Mode        = BRepGraph_ChildExplorer::TraversalMode::DirectChildren;
   //!   aConfig.TargetKind  = BRepGraph_NodeId::Kind::Face;
   //!   aConfig.StartLoc    = aParentLocation;
   //!   aConfig.StartOri    = TopAbs_REVERSED;
   //!   for (auto [id, loc, ori] : BRepGraph_ChildExplorer(aGraph, aRoot, aConfig)) { ... }
   //! @endcode
   struct Config
   {
     TraversalMode Mode = TraversalMode::Recursive;
     std::optional<BRepGraph_NodeId::Kind>
       TargetKind;                                    //!< Emit only this kind (no value = emit all).
     std::optional<BRepGraph_NodeId::Kind> AvoidKind; //!< Do not descend into this kind.
     bool                                  EmitAvoidKind =
       false; //!< Emit matching avoid-kind nodes once before skipping their subtree.
     bool               AccumulateLocation    = true; //!< Compose Location down the walk.
     bool               AccumulateOrientation = true; //!< Compose Orientation down the walk.
     TopLoc_Location    StartLoc;                     //!< Initial accumulated location.
     TopAbs_Orientation StartOri = TopAbs_FORWARD;    //!< Initial accumulated orientation.
   };
 
   //! Preferred long-term constructor: all tuning knobs in `Config`.
   //! @param[in] theGraph graph to walk
   //! @param[in] theRoot  root node where the walk begins
   //! @param[in] theConfig traversal configuration (mode, target kind, avoid kind, etc.)
   Standard_EXPORT BRepGraph_ChildExplorer(const BRepGraph&       theGraph,
                                           const BRepGraph_NodeId theRoot,
                                           const Config&          theConfig);
 
   //! Explore all descendants of the root node using recursive traversal.
   //! @param[in] theGraph graph to walk
   //! @param[in] theRoot  root node where the walk begins
   Standard_EXPORT BRepGraph_ChildExplorer(const BRepGraph&       theGraph,
                                           const BRepGraph_NodeId theRoot);
 
   //! Explore descendants of the root node using the given traversal mode.
   //! @param[in] theGraph graph to walk
   //! @param[in] theRoot  root node where the walk begins
   //! @param[in] theMode  traversal strategy (recursive or direct children)
   Standard_EXPORT BRepGraph_ChildExplorer(const BRepGraph&       theGraph,
                                           const BRepGraph_NodeId theRoot,
                                           TraversalMode          theMode);
 
   //! Explore descendants while pruning branches at the avoid kind.
   //! @param[in] theGraph        graph to walk
   //! @param[in] theRoot         root node where the walk begins
   //! @param[in] theAvoidKind    node kind to avoid descending into
   //! @param[in] theEmitAvoidKind if true, emit matching avoid-kind nodes once before skipping
   //! @param[in] theMode         traversal strategy
   Standard_EXPORT BRepGraph_ChildExplorer(const BRepGraph&                             theGraph,
                                           const BRepGraph_NodeId                       theRoot,
                                           const std::optional<BRepGraph_NodeId::Kind>& theAvoidKind,
                                           bool          theEmitAvoidKind,
                                           TraversalMode theMode = TraversalMode::Recursive);
 
   //! Explore only descendants of the given target kind.
   //! @param[in] theGraph     graph to walk
   //! @param[in] theRoot      root node where the walk begins
   //! @param[in] theTargetKind kind of nodes to emit
   Standard_EXPORT BRepGraph_ChildExplorer(const BRepGraph&       theGraph,
                                           const BRepGraph_NodeId theRoot,
                                           BRepGraph_NodeId::Kind theTargetKind);
 
   //! Explore only descendants of the given target kind using the given traversal mode.
   //! @param[in] theGraph     graph to walk
   //! @param[in] theRoot      root node where the walk begins
   //! @param[in] theTargetKind kind of nodes to emit
   //! @param[in] theMode      traversal strategy
   Standard_EXPORT BRepGraph_ChildExplorer(const BRepGraph&       theGraph,
                                           const BRepGraph_NodeId theRoot,
                                           BRepGraph_NodeId::Kind theTargetKind,
                                           TraversalMode          theMode);
 
   //! Explore descendants of the given target kind while pruning branches at the avoid kind.
   //! @param[in] theGraph        graph to walk
   //! @param[in] theRoot         root node where the walk begins
   //! @param[in] theTargetKind   kind of nodes to emit
   //! @param[in] theAvoidKind    node kind to avoid descending into
   //! @param[in] theEmitAvoidKind if true, emit matching avoid-kind nodes once before skipping
   //! @param[in] theMode         traversal strategy
   Standard_EXPORT BRepGraph_ChildExplorer(const BRepGraph&       theGraph,
                                           const BRepGraph_NodeId theRoot,
                                           BRepGraph_NodeId::Kind theTargetKind,
                                           const std::optional<BRepGraph_NodeId::Kind>& theAvoidKind,
                                           bool          theEmitAvoidKind,
                                           TraversalMode theMode = TraversalMode::Recursive);
 
   //! Explore only descendants of the given target kind starting from a product.
   //! @param[in] theGraph     graph to walk
   //! @param[in] theProduct   product whose occurrences and topology are explored
   //! @param[in] theTargetKind kind of nodes to emit
   Standard_EXPORT BRepGraph_ChildExplorer(const BRepGraph&          theGraph,
                                           const BRepGraph_ProductId theProduct,
                                           BRepGraph_NodeId::Kind    theTargetKind);
 
   //! Disambiguates non-product typed ids from the ProductId-specific overload
   //! family above and keeps them on the generic NodeId traversal path.
   //! @param[in] theGraph     graph to walk
   //! @param[in] theRoot      typed root node where the walk begins
   //! @param[in] theTargetKind kind of nodes to emit
   template <BRepGraph_NodeId::Kind TheKind,
             typename std::enable_if_t<TheKind != BRepGraph_NodeId::Kind::Product, int> = 0>
   BRepGraph_ChildExplorer(const BRepGraph&                       theGraph,
                           const BRepGraph_NodeId::Typed<TheKind> theRoot,
                           BRepGraph_NodeId::Kind                 theTargetKind)
       : BRepGraph_ChildExplorer(theGraph, BRepGraph_NodeId(theRoot), theTargetKind)
   {
   }
 
   //! Explore only descendants of the given target kind starting from a product,
   //! using the given traversal mode.
   //! @param[in] theGraph     graph to walk
   //! @param[in] theProduct   product whose occurrences and topology are explored
   //! @param[in] theTargetKind kind of nodes to emit
   //! @param[in] theMode      traversal strategy
   Standard_EXPORT BRepGraph_ChildExplorer(const BRepGraph&          theGraph,
                                           const BRepGraph_ProductId theProduct,
                                           BRepGraph_NodeId::Kind    theTargetKind,
                                           TraversalMode             theMode);
 
   //! Disambiguates non-product typed ids from the ProductId-specific overload
   //! family above and keeps them on the generic NodeId traversal path.
   //! @param[in] theGraph     graph to walk
   //! @param[in] theRoot      typed root node where the walk begins
   //! @param[in] theTargetKind kind of nodes to emit
   //! @param[in] theMode      traversal strategy
   template <BRepGraph_NodeId::Kind TheKind,
             typename std::enable_if_t<TheKind != BRepGraph_NodeId::Kind::Product, int> = 0>
   BRepGraph_ChildExplorer(const BRepGraph&                       theGraph,
                           const BRepGraph_NodeId::Typed<TheKind> theRoot,
                           BRepGraph_NodeId::Kind                 theTargetKind,
                           TraversalMode                          theMode)
       : BRepGraph_ChildExplorer(theGraph, BRepGraph_NodeId(theRoot), theTargetKind, theMode)
   {
   }
 
   //! Explore only descendants of the given target kind with explicit location/orientation control.
   //! @param[in] theGraph     graph to walk
   //! @param[in] theRoot      root node where the walk begins
   //! @param[in] theTargetKind kind of nodes to emit
   //! @param[in] theCumLoc    if true, accumulate location down the walk
   //! @param[in] theCumOri    if true, accumulate orientation down the walk
   //! @param[in] theMode      traversal strategy
   Standard_EXPORT BRepGraph_ChildExplorer(const BRepGraph&       theGraph,
                                           const BRepGraph_NodeId theRoot,
                                           BRepGraph_NodeId::Kind theTargetKind,
                                           bool                   theCumLoc,
                                           bool                   theCumOri,
                                           TraversalMode theMode = TraversalMode::Recursive);
 
   //! Explore only descendants of the given target kind starting from a product,
   //! with explicit location/orientation control.
   //! @param[in] theGraph     graph to walk
   //! @param[in] theProduct   product whose occurrences and topology are explored
   //! @param[in] theTargetKind kind of nodes to emit
   //! @param[in] theCumLoc    if true, accumulate location down the walk
   //! @param[in] theCumOri    if true, accumulate orientation down the walk
   //! @param[in] theMode      traversal strategy
   Standard_EXPORT BRepGraph_ChildExplorer(const BRepGraph&          theGraph,
                                           const BRepGraph_ProductId theProduct,
                                           BRepGraph_NodeId::Kind    theTargetKind,
                                           bool                      theCumLoc,
                                           bool                      theCumOri,
                                           TraversalMode theMode = TraversalMode::Recursive);
 
   //! Disambiguates non-product typed ids from the ProductId-specific overload
   //! family above and keeps them on the generic NodeId traversal path.
   //! @param[in] theGraph     graph to walk
   //! @param[in] theRoot      typed root node where the walk begins
   //! @param[in] theTargetKind kind of nodes to emit
   //! @param[in] theCumLoc    if true, accumulate location down the walk
   //! @param[in] theCumOri    if true, accumulate orientation down the walk
   //! @param[in] theMode      traversal strategy
   template <BRepGraph_NodeId::Kind TheKind,
             typename std::enable_if_t<TheKind != BRepGraph_NodeId::Kind::Product, int> = 0>
   BRepGraph_ChildExplorer(const BRepGraph&                       theGraph,
                           const BRepGraph_NodeId::Typed<TheKind> theRoot,
                           BRepGraph_NodeId::Kind                 theTargetKind,
                           bool                                   theCumLoc,
                           bool                                   theCumOri,
                           TraversalMode                          theMode = TraversalMode::Recursive)
       : BRepGraph_ChildExplorer(theGraph,
                                 BRepGraph_NodeId(theRoot),
                                 theTargetKind,
                                 theCumLoc,
                                 theCumOri,
                                 theMode)
   {
   }
 
   //! Explore only descendants of the given target kind with an explicit initial transform.
   //! @param[in] theGraph     graph to walk
   //! @param[in] theRoot      root node where the walk begins
   //! @param[in] theTargetKind kind of nodes to emit
   //! @param[in] theStartLoc  initial accumulated location
   //! @param[in] theStartOri  initial accumulated orientation
   //! @param[in] theMode      traversal strategy
   Standard_EXPORT BRepGraph_ChildExplorer(const BRepGraph&       theGraph,
                                           const BRepGraph_NodeId theRoot,
                                           BRepGraph_NodeId::Kind theTargetKind,
                                           const TopLoc_Location& theStartLoc,
                                           TopAbs_Orientation     theStartOri,
                                           TraversalMode theMode = TraversalMode::DirectChildren);
 
   //! Returns the traversal configuration this explorer was constructed with.
   //! Read-only - configuration is fixed for the lifetime of the explorer.
   [[nodiscard]] const Config& GetConfig() const { return myConfig; }
 
   //! True if another matching descendant is available.
   [[nodiscard]] bool More() const { return myHasMore; }
 
   //! Advance to the next matching descendant.
   Standard_EXPORT void Next();
 
   //! Current matching descendant node with accumulated location and orientation.
   [[nodiscard]] BRepGraphInc::NodeInstance Current() const
   {
     return {myCurrent, myLocation, myOrientation};
   }
 
   //! Returns the immediate parent of Current() in the explored path.
   //! Returns invalid NodeId when Current() is the root/self match.
   [[nodiscard]] Standard_EXPORT BRepGraph_NodeId CurrentParent() const;
 
   //! Returns how Current() is linked from CurrentParent().
   [[nodiscard]] Standard_EXPORT LinkKind CurrentLinkKind() const;
 
   //! Returns the exact parent-owned RefId for Current(), when the current step
   //! is represented by a reference entry. Returns invalid RefId for structural
   //! links without a dedicated ref entry such as CoEdge->Edge,
   //! Occurrence->Product/topology-root.
   [[nodiscard]] Standard_EXPORT BRepGraph_RefId CurrentRef() const;
 
   //! Returns the explicit concrete traversal path from the explorer root to Current().
   [[nodiscard]] Standard_EXPORT BRepGraph_UsagePath CurrentUsagePath() const;
 
   //! Returns the accumulated location at the most recent ancestor of the given kind.
   //! @param[in] theKind node kind to search for in the ancestor chain
   //! @return accumulated location at the matching ancestor
   [[nodiscard]] Standard_EXPORT TopLoc_Location
     LocationOf(const BRepGraph_NodeId::Kind theKind) const;
 
   //! Returns the node id of the most recent ancestor of the given kind.
   //! @param[in] theKind node kind to search for in the ancestor chain
   //! @return node id of the matching ancestor
   [[nodiscard]] Standard_EXPORT BRepGraph_NodeId NodeOf(const BRepGraph_NodeId::Kind theKind) const;
 
   //! Returns the accumulated location at the given stack level.
   //! @param[in] theLevel zero-based stack depth (0 = root)
   //! @return accumulated location at the specified level
   [[nodiscard]] Standard_EXPORT TopLoc_Location LocationAt(const int theLevel) const;
 
   //! Returns the node id at the given stack level.
   //! @param[in] theLevel zero-based stack depth (0 = root)
   //! @return node id at the specified level
   [[nodiscard]] Standard_EXPORT BRepGraph_NodeId NodeAt(const int theLevel) const;
 
   //! Number of valid ancestor frames currently on the stack (excluding the
   //! sentinel below the root). O(1); avoids the O(depth^2) NodeAt(i) walk used
   //! to compute container priority in selection-mode building.
   [[nodiscard]] int Depth() const noexcept { return myStackTop < 0 ? 0 : myStackTop + 1; }
 
   //! Returns an STL-compatible iterator for range-based for loops.
   NCollection_ForwardRangeIterator<BRepGraph_ChildExplorer> begin()
   {
     return NCollection_ForwardRangeIterator<BRepGraph_ChildExplorer>(this);
   }
 
   //! Returns a sentinel marking the end of iteration.
   NCollection_ForwardRangeSentinel end() const { return NCollection_ForwardRangeSentinel{}; }
 
 private:
   struct StackFrame
   {
     BRepGraph_NodeId   Node;
     uint32_t           NextChildIdx   = 0;
     int                StepFromParent = -1;
     BRepGraph_RefId    Ref; //!< RefId resolved at push time (O(1) in CurrentRef)
     TopLoc_Location    AccLocation;
     TopAbs_Orientation AccOrientation = TopAbs_FORWARD;
   };
 
   Standard_EXPORT void advance();
 
   void startTraversal(const TopLoc_Location& theStartLoc, TopAbs_Orientation theStartOri);
 
   static std::optional<BRepGraph_NodeId::Kind> normalizeAvoidKind(
     const std::optional<BRepGraph_NodeId::Kind>& theAvoidKind,
     const std::optional<BRepGraph_NodeId::Kind>& theTargetKind);
 
   static bool canContainTarget(BRepGraph_NodeId::Kind theParentKind,
                                BRepGraph_NodeId::Kind theTargetKind);
 
   static bool canHaveChildren(BRepGraph_NodeId::Kind theNodeKind);
 
   void setCurrentFromFrame(const int theFrameIndex);
 
   [[nodiscard]] bool shouldDescendFromCurrent() const;
 
   [[nodiscard]] bool matchesTarget(const BRepGraph_NodeId theNode) const
   {
     return myConfig.TargetKind.has_value() && theNode.NodeKind == *myConfig.TargetKind;
   }
 
   [[nodiscard]] bool matchesAvoid(const BRepGraph_NodeId theNode) const
   {
     return myConfig.AvoidKind.has_value() && theNode.NodeKind == *myConfig.AvoidKind;
   }
 
   [[nodiscard]] bool shouldEmit(const BRepGraph_NodeId theNode) const
   {
     const bool isAvoid = matchesAvoid(theNode);
     const bool isFind =
       !myConfig.TargetKind.has_value() || theNode.NodeKind == *myConfig.TargetKind;
     return myConfig.EmitAvoidKind ? (isFind || isAvoid) : (isFind && !isAvoid);
   }
 
   void pushFrame(const StackFrame& theFrame);
 
   void popFrame();
 
   StackFrame& topFrame() { return myStack[myStackTop]; }
 
   const StackFrame& topFrame() const { return myStack[myStackTop]; }
 
   static constexpr int THE_INLINE_STACK_SIZE = 16;
 
   const BRepGraph* myGraph = nullptr;
   BRepGraph_NodeId myRoot;
   Config           myConfig; //!< Traversal configuration - single source of truth.
 
   NCollection_LocalArray<StackFrame, THE_INLINE_STACK_SIZE> myStack;
   int                                                       myStackTop     = -1;
   int                                                       myCurrentFrame = -1;
 
   BRepGraph_NodeId   myCurrent;
   TopLoc_Location    myLocation;
   TopAbs_Orientation myOrientation = TopAbs_FORWARD;
   bool               myHasMore     = false;
 };
 
 #endif // _BRepGraph_ChildExplorer_HeaderFile

This page was automatically generated by the 2.3.7 LXR engine. The LXR team