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, relation-table parent navigation, 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: Shapes().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. Shapes().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 (persistent metadata / observers) or BRepGraph_CacheRegistry (typed algorithm-computed transient cache services). 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 owner-scoped geometry/mesh representation slots (Surface, Curve3D, Curve2D, Triangulation, Polygon).
  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, coedges 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 relation tables 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.

Lightweight owner-bound base for transient graph cache services.
A cache service stores typed, recomputable, graph-local data such as bounding boxes, UV bounds, or display-resolution results. The registry owns only service identity and lifetime binding; concrete caches own their own typed storage and validate freshness lazily via graph generation counters.

Cache for derived edge, wire, and shell properties.
Each query is independent and caches only its own result. Callers request specific values (IsDegenerated, SameParameter, etc.) and the cache computes + stores only what is needed.

Iterator over registered cache families in a BRepGraph_CacheRegistry.
Supports OCCT More()/Next()/Value() pattern and STL range-for via begin()/end().

GUID-keyed runtime registry of graph cache services.
Stores registered cache services in a stable slot array for O(1) slot access and a GUID-to-slot map for lookup by stable public identity. Cache services own their typed transient data; this registry only manages identity and owner binding.

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 -> 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.

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 copy modes:

• External: source and target are different graphs. Target receives the copied data.
• Self-copy: source and target are the same graph. The specified sub-graph is duplicated with new entity IDs; shared dependencies (geometry, vertices referenced from outside the sub-graph) are preserved.
  Geometry and mesh policies are controlled by the GeomPolicy and MeshPolicy enums.
  Typical usage

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

Immutable context passed to layer copy callbacks.
The structural copy algorithm owns remap construction. Layers receive this context and decide how to copy their own representation without exposing layer details back to BRepGraph_Copy.

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 relation 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