Topology selection

Topology selections express feature intent as set queries. They never store a face index, edge enumeration position, OCCT handle, or transient kernel key.

Query roots

topology.faces
topology.edges
topology.vertices

Every query is typed by topology kind. A face query cannot accidentally be used where a fillet expects edges.

Origin and role

const endCap = topology.faces
  .createdBy(extrusion, { role: "extrude.face.end-cap" })
  .select();

const sideFromSketchEdge = topology.faces
  .createdBy(extrusion, {
    role: "extrude.face.side",
    source: { sketch: profile, entity: "outline.e1" },
  })
  .select();

const carriedRim = topology.edges
  .createdBy(extrusion, {
    role: "extrude.edge.end-rim",
    source: { sketch: profile, entity: "outline.e1" },
  })
  .and(topology.edges.modifiedBy(moved))
  .select();

createdBy means the feature introduced the item. modifiedBy means it is in the feature’s output lineage as a modified item. Roles identify semantic classes; the optional sketch source distinguishes members created from one authored entity.

Geometric predicates

Faces support:

topology.faces.surface("plane");
topology.faces.normal(scalarVec3(0, 0, 1), deg(0.1));
topology.faces.radius(mm(10), mm(1e-6));

Edges support:

topology.edges.curve("line");
topology.edges.direction(scalarVec3(1, 0, 0), deg(0.1));
topology.edges.radius(mm(4), mm(1e-6));

Vertices support:

topology.vertices.position(
  vec3(mm(0), mm(0), mm(0)),
  mm(1e-6),
);

Geometric predicates are useful filters, but semantic origin is usually more stable when it exists. Coordinates alone are especially fragile under parameter changes and transforms.

Logical composition

const query = topology.edges
  .createdBy(extrusion, { role: "extrude.edge.end-rim" })
  .and(topology.edges.curve("line"))
  .and(topology.edges.direction(scalarVec3(1, 0, 0)).not());

const eitherCap = topology.faces
  .createdBy(extrusion, { role: "extrude.face.start-cap" })
  .or(topology.faces.createdBy(extrusion, { role: "extrude.face.end-cap" }));

and and or flatten, deduplicate, and canonicalize their operands. not() negates a query inside the current topology universe.

Adjacency

Adjacency crosses topology kinds through a completed selection:

const cap = topology.faces
  .createdBy(extrusion, { role: "extrude.face.end-cap" })
  .select();

const capEdges = topology.edges.adjacentTo(cap).atLeast(1);
const edgeFaces = topology.faces.adjacentTo(capEdges).atLeast(1);
const edgeVertices = topology.vertices.adjacentTo(capEdges).atLeast(2);

The nested selection keeps its own cardinality requirement. A failure inside adjacency is not treated as an empty set.

Cardinality is required intent

Finish a query with one of:

query.select();        // exactly one
query.exactly(4);      // exactly four
query.atLeast(2);      // two or more
query.between(2, 8);   // inclusive range

There is no unbounded “take whatever matched” selection. Cardinality bounds the set the selector matches, so a parameter or upstream feature change that moves the match count outside that bound fails the feature instead of silently changing its selected input. select() and exactly(n) fail on any change in count. atLeast(n) and between(min, max) accept every count in their range, so an item gained or lost inside that range is not reported. For shell openings and draft faces, the matched set is exactly the set of faces the operation receives. Fillet and chamfer edges are different: each selected edge is a seed that expands after the cardinality check to its maximal tangent contour, where consecutive edges meet tangentially and the faces on both sides also continue tangentially. A select() seed can therefore treat several connected edges, and an upstream change that makes a neighboring edge and its faces continue tangentially can grow the treated contour without a diagnostic. See fillet and chamfer.

Explain a selection

explainTopologySelection evaluates the query against a detached topology snapshot and returns a frozen aggregate report. It records the outcome, topology kind, snapshot history, candidates considered and matched, required cardinality, and the resolved keys on success. Failure diagnostics carry additional bounded candidate summaries when the evaluator can provide them; the public explanation does not expose per-candidate or logical-branch traces. Use explanations for tooling and debugging; do not parse human-readable diagnostic messages to recover selector state.

Backend requirements

The evaluator checks topology capability metadata before invoking the consuming feature. A backend that cannot provide the requested surface, curve, lineage, source, or adjacency evidence fails explicitly. It does not approximate a semantic query with enumeration order.

Getting started

Modeling

Evaluation

Analysis and interchange