BRepGraph: Making OCCT Topology Explicit

[dpasukhi]

TopoDS_Shape is one of the most important parts of OCCT. It is compact, flexible, and proven by many years of industrial use. It is also the common language used by many OCCT algorithms, importers, exporters, and applications.

At the same time, developers who work deeply with TopoDS_Shape often meet the same class of problems: some topology is implicit, some data can be stored in more than one place, some relations are hidden behind implementation details, and some metadata becomes stale after editing or import.

BRepGraph is designed to make these hidden contracts explicit.

TopoDS remains an important OCCT shape model and compatibility boundary. The goal of BRepGraph is different: provide a graph-oriented model where topology, references, geometry, mesh, assembly placement, identity, metadata, caches, ownership, and mutation are represented as separate concepts.

Compatibility note

The BRepGraph interface will change slightly in OCCT 8.1 and in development versions after 8.0. This is intentional. The current cleanup is needed to provide a cleaner public interface, remove duplicated or temporary entry points, and optimize the model before the API becomes harder to change.

The design direction is stable, but some names and access patterns may still be adjusted.

From shape occurrence to explicit graph data

TopoDS often answers topology questions through a shape occurrence. A TopoDS_Shape contains orientation, location, and a shared TShape. The actual data is then stored behind the TShape: vertices, edges, faces, curves, p-curves, surfaces, triangulations, polygons, tolerances, regularity, and other representation details.

This model is powerful, but it mixes several concepts in one object. BRepGraph separates them.

flowchart LR
  subgraph TopoDS["TopoDS"]
    Shape["TopoDS_Shape occurrence"]
    TShape["Shared TShape"]
    Loc["Location"]
    Ori["Orientation"]
    Reps["Hidden representation variants"]
    Maps["Temporary algorithm maps"]
  end

  subgraph BRepGraph["BRepGraph"]
    Def["Topology definitions"]
    Ref["References / usages"]
    Geom["Geometry representations"]
    Mesh["Mesh representations"]
    Asm["Products and occurrences"]
    UID["UID / RefUID / RepUID"]
    Layer["Persistent layers"]
    Owner["Ownership layer"]
    Stamp["Modification stamps"]
    Cache["Computed caches"]
  end

  Shape --> Ref
  TShape --> Def
  Loc --> Ref
  Ori --> Ref
  Reps --> Geom
  Reps --> Mesh
  Maps --> Cache
  Def --> UID
  Ref --> UID
  Geom --> UID
  Mesh --> UID
  Def --> Layer
  Def --> Owner
  Def --> Stamp

Loading

In BRepGraph, an edge definition is not the same thing as the use of this edge in a wire. A face definition is not the same thing as a placed face occurrence. Persistent metadata is not the same thing as a temporary cache. This separation is the main reason why BRepGraph can remove many old special cases.

1. Natural-bound faces become explicit topology

One of the most important changes is the removal of the natural-bound face branch.

In TopoDS, a face can use the natural domain of its surface instead of explicit boundary topology. This creates two processing modes: a face can have wires, edges, and vertices, or it can have no explicit lower topology and the boundary must be inferred from the surface.

This looks like a small flag, but it creates many special cases. Algorithms must always remember that a face can be a normal bounded topology object or a surface-only object with implied boundaries. This affects traversal, validation, primitive generation, persistence, selection, topological naming, and reconstruction.

BRepGraph uses a stricter rule: a bounded geometric face should provide explicit topology below it. The boundary is represented as face -> wire -> coedge -> edge -> vertex. If a source TopoDS face uses natural bounds, population should normalize it into explicit topology when finite bounds are available. If the face is truly unbounded, it should be handled as a special model case, not hidden behind a normal bounded face flag.

This matters because many advanced operations need real topology. A selector cannot reliably bind to an edge that does not exist. A naming system cannot name a boundary that is only implied by a surface domain.

2. Locations move to references

TopoDS can carry location information in several places. For edges, there can be a location on the topological occurrence and another location connected with the geometric representation. Polygon data may follow different rules. For faces, there can be a shape location and a surface location, while triangulation does not always use the same path as the surface.

This creates a common class of bugs: transformation is applied twice, not applied at all, applied in the wrong frame, or compared through a location chain that is geometrically equal but structurally different.

BRepGraph moves placement into explicit references. Geometry is stored in a definition frame. A concrete use of this geometry has a reference with its own context. Algorithms can work either with a definition or with a placed occurrence, but this choice becomes explicit.

This also improves lookup. In TopoDS, two equal gp_Trsf transformations can produce different TopLoc_Location chains. Depending on the hasher, they can behave as different keys. In BRepGraph, a placed use is a reference object with an id and, when needed, a durable RefUID. Search can use graph identity instead of relying on equivalent location chains being built in exactly the same way.

3. Coedges make edge-face data explicit

In TopoDS, TEdge can store curve-on-surface data through several internal representation classes. A p-curve is not always a simple direct relation between one edge and one face. It can depend on representation variants, closed-surface cases, surface handles, locations, and implicit rules.

BRepGraph introduces an explicit coedge concept. A coedge is the use of an edge by a wire on a face. This is the natural place for data that belongs to one edge-face usage: edge orientation in this wire, p-curve on this face, seam half identity, relation to the owning wire and face, and local usage context.

flowchart TD
  Face["Face definition"]
  Wire["Wire definition"]
  CoEdge1["Coedge: edge use on face"]
  CoEdge2["Coedge: second seam half"]
  Edge["Edge definition"]
  V1["Start vertex"]
  V2["End vertex"]
  C3D["3D curve representation"]
  C2D1["2D curve for first coedge"]
  C2D2["2D curve for seam coedge"]

  Face --> Wire
  Wire --> CoEdge1
  Wire --> CoEdge2
  CoEdge1 --> Edge
  CoEdge2 --> Edge
  Edge --> V1
  Edge --> V2
  Edge --> C3D
  CoEdge1 --> C2D1
  CoEdge2 --> C2D2

Loading

This solves two important problems.

First, curve-on-surface variants are no longer hidden as a surprise inside an edge representation hierarchy. The p-curve is attached to the usage where it is meaningful.

Second, p-curve invalidation becomes more controlled. In TopoDS, a curve-on-surface may be connected to a surface pointer. If the face later changes its surface handle, the old p-curve can become stale, but the connectivity is not strong enough to force cleanup. In BRepGraph, the p-curve belongs to the coedge and the coedge belongs to the face context. When a face representation changes, affected coedges, layers, and caches can be invalidated through graph mutation rules.

4. INTERNAL and EXTERNAL move out of core topology

TopoDS supports four orientations: FORWARD, REVERSED, INTERNAL, and EXTERNAL. This is useful for preserving some special constructs, but it is not a clean model for a normal incidence graph. In most topological relations, the core question is whether a child is used forward or reversed.

BRepGraph keeps only forward and reversed orientation in the core topology model. Other TopoDS-specific cases are moved to a supplemental topology layer. This allows OCCT to preserve special data for round trips and diagnostics without contaminating the main graph relations.

The result is simpler traversal and simpler algorithm logic. The core graph has fewer exceptional states, while the supplemental layer still keeps information needed for compatibility.

5. Persistence uses durable identity, not iteration order

TopoDS can be persistent enough for simple read-write workflows when the shape is not edited. In that case, index-based iteration can remain stable enough. But this is not a strong identity model. Once editing starts, iteration order and local indexes are not enough for durable references, patches, selections, history, or future semantic naming.

BRepGraph separates runtime ids from durable UIDs. Runtime ids are compact typed addresses into current graph storage. They are efficient for algorithms working inside the current model. Durable UIDs are persistent anchors for long-lived data.

BRepGraph can provide identity for topology, references, geometry, mesh, assembly occurrences, and other graph items. This makes it a better base for persistent selection, diff and patch workflows, history, undo/redo, external references, semantic topological naming, and direct graph persistence.

6. Regularity, ownership, and other metadata become layers

TopoDS stores some information directly in topology, including regularity data related to faces and edges. In practice, this information may become stale quickly or may be incomplete from the beginning. After editing, healing, replacement, or import, algorithms often have to decide whether to trust it, recompute it, or ignore it.

BRepGraph moves this kind of data to layers. For example, regularity is stored in BRepGraph_LayerRegularity.

This is more than a different storage place. A layer is a controlled persistent side-data mechanism. It can have lifecycle behavior when graph items are removed, replaced, compacted, or modified. This is better than forcing every algorithm to maintain its own side maps or manually copy attributes after each operation.

Ownership and locking also become explicit. In TopoDS-based code, it is often unclear which subsystem owns a sub-shape or why some item should not be modified. It may be controlled by an importer, algorithm, document, assembly occurrence, feature, or application-level object. BRepGraph moves this into an ownership layer, so editing code can check who owns a graph item before changing topology, geometry, mesh, or metadata.

Typical layer candidates are names, colors, imported metadata, regularity, ownership, locks, source bindings, supplemental topology, and future naming data.

7. Modification state becomes a stamp, not an unclear boolean

A boolean modification flag is often too weak. It can say that something was changed, but it does not explain when it changed, whether a cache was built before or after the edit, or when the flag should be reset.

BRepGraph uses integer modification stamps. A uint32_t stamp can be increased when an item is edited. Cached data, layers, reconstructed shapes, and dependent algorithms can store the stamp they were built from and compare it with the current value.

This turns modification tracking from an ambiguous yes/no state into a version check. A service does not only need to know that something was modified. It needs to know whether its own data is still valid for the current edition of the element.

8. Caches become controlled and self-invalidating

CAD algorithms constantly compute data that should not necessarily be stored as persistent model data: bounding boxes, UV bounds, classification helpers, reconstructed shapes, wire analysis, acceleration structures, and many other derived values.

In TopoDS-based workflows, such caches are often local to an algorithm or stored in application-level side maps. Invalidation is manual and easy to get wrong.

BRepGraph provides a graph-local cache concept. A cache can calculate data on request and validate freshness through graph generation counters or modification stamps. Direct changes can update the item generation, while child changes can propagate subtree generation upward. This makes lazy recomputation safer and avoids clearing all cached data after every edit.

The split is simple: layers are for persistent metadata, caches are for computed data, and mutation must update the freshness model.

9. Populate is normalization, not only conversion

BRepGraphInc_Populate should not be treated as a simple TopoDS-to-graph copy loop. It is a normalization boundary.

TopoDS is permissive. It can keep implicit bounds, hidden p-curve variants, duplicated locations, stale regularity, source-specific constructs, and algorithm-dependent assumptions. BRepGraph is stricter. Population is the place where these hidden contracts are converted into explicit graph data.

A good populate process can deduplicate shared TShape definitions, deduplicate geometry and mesh representations where possible, create explicit face boundary topology, extract p-curves without generating phantom data, bind p-curves to coedges, store geometry in definition frames, move placement to references, extract regularity into a layer, store source bindings for diagnostics, move unsupported special cases into supplemental topology, and rebuild relation tables.

This is why population is part of the architecture. It is the bridge from a flexible legacy representation to a stricter graph model.

10. Bidirectional traversal is part of the model

Many algorithms start from a solid and go down to faces, edges, and vertices. But CAD applications also need the reverse questions all the time: which faces use this edge, which wires contain this coedge, which shells contain this face, which product occurrences reach this topology, and which exact occurrence path was selected.

TopoDS can answer these questions, but usually through temporary maps built by each algorithm. Different algorithms may build different reverse views.

BRepGraph stores relation tables and incoming maps as part of the model. Ordered child relations preserve topology order, while reverse relations allow parent and adjacency queries without rebuilding the same maps again and again.

flowchart LR
  Solid --> Shell
  Shell --> Face
  Face --> Wire
  Wire --> CoEdge
  CoEdge --> Edge
  Edge --> Vertex

  Vertex -. incoming .-> Edge
  Edge -. incoming .-> CoEdge
  CoEdge -. owner .-> Wire
  Wire -. parent .-> Face
  Face -. parent .-> Shell
  Shell -. parent .-> Solid

Loading

This is useful for editing, diagnostics, selection, invalidation, attribute transfer, and topological naming.

11. Assembly occurrence identity becomes explicit

TopoDS can represent sharing through repeated shapes with locations, but CAD applications often need more than that. They need product definitions, placed occurrences, occurrence paths, reused sub-assemblies, and stable selection of one concrete instance.

BRepGraph makes products and occurrences part of the model. A product can be shared by several occurrences. Each occurrence has its own reference and placement. A selected face or edge can be connected not only to a topology definition, but also to the occurrence path that produced it.

This helps avoid the common ambiguity between “this edge definition” and “this edge in this exact assembly instance”.

12. Geometry, mesh, and display cache are separated

In many TopoDS workflows, triangulation is stored close to the face, while geometry follows a different representation path. This is convenient for many algorithms, but it becomes less clear when an application wants to load structure first, delay geometry loading, keep persistent mesh data, or use temporary display caches.

BRepGraph separates geometry representations, persistent mesh representations, and computed runtime caches. This makes it possible to treat exact geometry, stored mesh, and temporary acceleration data as different payloads with different lifecycles.

This is also important for ODE persistence. The graph can be stored directly, and payload policy can decide what is written or loaded: structure, geometry, mesh, or deferred payloads.

13. ODE stores graph data directly

The traditional .brep format is useful and fast enough, but it is not optimized for a graph model. If an application wants BRepGraph after loading .brep, it must first load TopoDS and then build graph data from it.

ODE stores BRepGraph directly: topology rows, reference rows, representation selectors, UIDs, products, occurrences, geometry, and mesh payloads. Depending on the model and payload policy, ODE is expected to be about 2-5x smaller on disk and 2-10x faster to read into the graph than workflows that load .brep first and then rebuild graph data.

Direct graph persistence avoids paying the TopoDS-to-graph conversion cost after every load.

14. Topological naming needs explicit topology

Topological naming is very difficult when topology is implicit. A selector cannot reliably bind to “top rim”, “sector start edge”, or “pole vertex” if those items do not exist as graph objects.

BRepGraph provides the low-level base for better naming: explicit graph items, durable UIDs, reference identity, occurrence paths, history data, and mutation stamps. Primitive builders can also author semantic topology directly instead of relying on surface-only faces and hidden boundaries.

The principle:

Names attach to explicit graph items, not to hidden surface bounds.

Summary

BRepGraph is mainly about removing hidden branches from CAD topology code.

It turns implicit TopoDS contracts into explicit graph records: face boundaries, coedges, references, UIDs, layers, ownership, modification stamps, caches, relation tables, assembly occurrences, and persistent graph storage.

This costs migration work, and the OCCT 8.1/development API cleanup is part of that work. The expected benefit is a model that is easier to validate, persist, diff, patch, cache, traverse, edit, and eventually name semantically.