BRepGraph

Topology-geometry graph over TopoDS / BRep.
Stores B-Rep topology as flat entity vectors (incidence-table model) with integer cross-references, enabling cache-friendly traversal, O(1) upward navigation via reverse indices, and parallel face-level geometry extraction.
Key design concepts:

• NodeId (Kind + Index): lightweight typed address into per-kind vectors.
• UID (Kind + Counter): persistent identity surviving compaction/reorder.
• RepId (Kind + Index): separate geometry/mesh addressing (Surface, Curve3D, Curve2D, Triangulation, Polygon) decoupled from topology nodes.
• CoEdge: half-edge entity owning PCurve data for each edge-face binding; seam edges use paired CoEdges with opposite Orientation (Parasolid convention).
• Lifecycle: BRepGraph_Builder::Add() populates from TopoDS_Shape; Editor() is the single mutation entry point for both structural creation/removal (Add*, Remove*, Append*) and field-level RAII-scoped mutation (Mut*()) with automatic cache invalidation and upward SubtreeGen propagation.
  Per-occurrence data (orientation, location) lives on incidence refs. Definition types are aliases to BRepGraphInc entity structs.
  Grouped View API
  Related methods are grouped behind lightweight view objects. Include the corresponding header (e.g. BRepGraph_TopoView.hxx) to use.
  Thread safety
  Const query methods are safe for concurrent reads. Concurrent reads during active mutation still require external synchronization. Deferred invalidation (BRepGraph_DeferredScope) batches SubtreeGen propagation; concurrent Editor().Mut*() calls during deferred mode still require external serialization. BRepGraph_Builder::Add() is internally parallel when requested.
  UID persistence
  UIDs use monotonic counters (not vector indices), persisting across Compact() and node removal. Only BRepGraph::Clear() resets counters (new generation). See BRepGraph_UID.hxx for the serialization contract.
  Extension model
  Extend via BRepGraph_Layer (per-node attributes) or BRepGraph_TransientCache (algorithm-computed caches). Direct storage extension is not supported.
  ID systems
  Four ID types with different stability guarantees:
• NodeId (Kind + per-kind Index): fast graph-local address. NOT stable across Compact(). Use for in-graph traversal and short-lived algorithm temporaries.
• UID (Kind + monotonic Counter): persistent identity surviving Compact() and node removal. Use for cross-session storage, history tracking, and external references.
• RefId (Kind + per-kind Index): same stability as NodeId, but addresses reference entries (Shell->Solid binding, Face->Shell binding, CoEdge->Wire binding) rather than defs.
• RepId (Kind + per-kind Index): addresses geometry/mesh representation objects (Surface, Curve3D, Curve2D, Triangulation, Polygon) independently of topology nodes.
  Iterator guide
  Choose the iterator that matches your traversal need:
• BRepGraph_Iterator<NodeType>: flat sequential scan of ALL definitions of one kind (e.g. every FaceDef, skipping removed). Use for bulk per-kind algorithms.
• BRepGraph_DefsIterator / BRepGraph_RefsIterator: single-level typed children of one parent (e.g. active shells of one solid, coedge refs of one wire). Zero allocation. Use when you have a specific parent and need its direct children.
• BRepGraph_ChildExplorer: depth-first downward walk from a root with accumulated location/orientation per step. Use when visiting descendants across multiple levels or when the global transform matters. Supports Recursive and DirectChildren modes.
• BRepGraph_ParentExplorer: upward walk via reverse indices from a starting node. Use when tracing which shells/solids/compounds contain a given face or edge.
• BRepGraph_RelatedIterator: single-level semantic neighbors (adjacent faces, boundary edges, incident vertices). No structural descent; no location accumulation.
• BRepGraph_WireExplorer: ordered edge traversal within a single wire, following connectivity order (graph equivalent of BRepTools_WireExplorer).

Static helper that ingests a TopoDS_Shape into a BRepGraph.

Descriptor of one transient cache family.
A cache kind defines stable public identity for one class of transient, recomputable per-node data such as bounding boxes or UV bounds. Instances are process-global descriptors registered in BRepGraph_CacheKindRegistry and referenced from graphs by dense runtime slots.

Process-global registry of cache kind descriptors.
Maps stable GUID identity to dense runtime slot index. Slot indices are an internal storage detail used by BRepGraph_TransientCache for O(1) indexing. The registry is shared across all BRepGraph instances in the current process, so cache-kind GUIDs should be globally unique.

Abstract base for transient per-node cache values.
Inherits from Standard_Transient and is stored via occ::handle<BRepGraph_CacheValue>. This uses OCCT's embedded refcount and is consistent with the Handle pattern used throughout the codebase.

Stack-based lazy downward hierarchy walker for BRepGraph with inline location/orientation accumulation.
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(assembly) -> Occurrences, Product(part) -> ShapeRoot, Occurrence -> Product.
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.

Graph compaction algorithm that reclaims removed node slots.
After deduplication or other operations that mark nodes as removed, this algorithm rebuilds the graph with dense index arrays, eliminating all removed nodes and reassigning indices to be contiguous.
Strategy: rebuild-and-swap. A fresh BRepGraph is constructed from non-removed nodes with remapped indices, then move-assigned into the input graph.

Graph-to-graph deep copy.
Produces a new BRepGraph from an existing one in a single bottom-up pass, avoiding the 5-7 traversals of BRepTools_Modifier used by BRepBuilderAPI_Copy.
Two modes:

• theCopyGeom = true (deep): geometry handles are cloned, result is fully independent.
• theCopyGeom = false (light): geometry handles are shared, only topology is duplicated.
  Typical usage

BRepGraphaGraph; BRepGraph_Builder::Add(aGraph,myShape); BRepGraphaCopy=BRepGraph_Copy::Perform(aGraph); TopoDS_ShapeaShape=aCopy.Shapes().Shape();

Internal storage for BRepGraph (PIMPL).
All topology definition data and UIDs live in myIncStorage. Access via myIncStorage.Edges, myIncStorage.Faces, etc.

Deep geometry deduplication algorithm over an existing BRepGraph.
This algorithm canonicalizes deep-equal geometry references (surfaces and 3D curves) using GeomHash hashers. It updates face/edge definition links to canonical geometry nodes and can record lineage in graph history.
First implementation intentionally does not merge edge/face definitions yet.

RAII guard for batch mutation scopes with deferred invalidation.
Activates deferred invalidation on construction and flushes it on destruction, followed by CommitMutation validation. Guarantees exception-safe cleanup: when this guard owns deferred mode, it is always closed and boundary checks are executed at scope exit. EndDeferredInvalidation() batch-propagates SubtreeGen upward, then CommitMutation() validates reverse-index consistency and active-entity counts.
Re-entrant: if deferred mode is already active (e.g., nested guard), the inner guard is a no-op. Only the outermost guard flushes and commits, so nested scopes do not create separate transaction or validation boundaries.
Usage:

{ BRepGraph_DeferredScopeaScope(theGraph); for(inti=0;i<N;++i) { //mutations } }//EndDeferredInvalidation+CommitMutationcalledhere