Finders & Queries
You build a part, then you need to do something to a specific feature: round the vertical edges, shell the top face, find the corner where two boolean operations met. Finders are how you select features. They are filters that compose: you start with "all edges of this shape" and narrow down by direction, length, curve type, position, or any combination.
The four finders
import { box, vertexFinder, edgeFinder, wireFinder, faceFinder } from 'brepjs/quick';
const b = box(20, 20, 20);
const vertices = vertexFinder().findAll(b); // 8
const edges = edgeFinder().findAll(b); // 12
const wires = wireFinder().findAll(b); // 6 (one outer wire per face)
const faces = faceFinder().findAll(b); // 6
console.log({
vertices: vertices.length,
edges: edges.length,
wires: wires.length,
faces: faces.length,
});findAll returns an array. findUnique returns a Result holding the single match, or an error when zero or several elements match. Filters chain; every call narrows the result.
Filter vocabulary
The full filter set, abbreviated. See the API Reference for exhaustive signatures.
Direction filters
import { box, edgeFinder, faceFinder, normalAt } from 'brepjs/quick';
const b = box(30, 20, 10);
edgeFinder().inDirection('Z').findAll(b); // edges parallel to Z
edgeFinder().inDirection([1, 1, 0]).findAll(b); // edges along (1,1,0), none in a box
faceFinder().inDirection('Z').findAll(b); // top + bottom faces
faceFinder()
.when((f) => normalAt(f)[2] < 0)
.findAll(b); // bottom face only (negative Z normal)For edges, "direction" means the edge's tangent at its midpoint (lines have a constant tangent; curves don't). For faces, it's the normal at the face's centre.
inDirection ignores sign: 'Z' and [0, 0, -1] both match [0, 0, 1] and [0, 0, -1]. For a specific orientation, test the normal in a .when() predicate as above.
Position filters
import { box, edgeFinder, faceFinder, faceCenter, getBounds } from 'brepjs/quick';
const b = box(30, 20, 10);
faceFinder()
.when((f) => faceCenter(f)[2] > 9.9)
.findAll(b); // top face
edgeFinder()
.when((e) => getBounds(e).xMin < 15 && getBounds(e).xMax > 15)
.findAll(b); // edges crossing x=15There are no dedicated position filters for edges and faces: pass a predicate to .when() that reads faceCenter(face) or getBounds(edge).
atDistance(distance, point) keeps elements at an exact distance from a point.
Length / area filters
import { box, sketchCircle, edgeFinder, faceFinder } from 'brepjs/quick';
const b = box(30, 20, 10);
edgeFinder().ofLength(30).findAll(b); // the four 30mm edges
faceFinder().ofArea(600).findAll(b); // the two 30x20 faces
const cyl = sketchCircle(10).extrude(20);
edgeFinder().ofCurveType('CIRCLE').findAll(cyl); // the circular edgesofLength(length, tolerance?) and ofArea(area, tolerance?) match a value within a tolerance (default 1e-3). For a range, use .when() with curveLength or measureArea.
Type filters
import { sketchCircle, faceFinder, edgeFinder } from 'brepjs/quick';
const cyl = sketchCircle(10).extrude(20);
faceFinder().ofSurfaceType('PLANE').findAll(cyl); // 2 (top, bottom)
faceFinder().ofSurfaceType('CYLINDRE').findAll(cyl); // 1 (side)
edgeFinder().ofCurveType('LINE').findAll(cyl); // 1, the seam edge on the side
edgeFinder().ofCurveType('CIRCLE').findAll(cyl); // 2Surface types: PLANE, CYLINDRE (OCCT's spelling), CONE, SPHERE, TORUS, BEZIER_SURFACE, BSPLINE_SURFACE, REVOLUTION_SURFACE, EXTRUSION_SURFACE, OFFSET_SURFACE, OTHER_SURFACE.
Curve types: LINE, CIRCLE, ELLIPSE, HYPERBOLA, PARABOLA, BEZIER_CURVE, BSPLINE_CURVE, OFFSET_CURVE, OTHER_CURVE.
Wire filters
import { box, faceFinder, wireFinder, outerWire } from 'brepjs/quick';
const b = box(30, 20, 10);
const oneFace = faceFinder().findAll(b)[0];
if (oneFace) {
wireFinder().isClosed().findAll(oneFace); // outer + inner closed loops
outerWire(oneFace); // just the outer boundary
}Vertex filters
import { box, vertexFinder } from 'brepjs/quick';
const b = box(30, 20, 10);
vertexFinder().withinBox([0, 0, 9.9], [30, 20, 10.1]).findAll(b); // top 4 corners
vertexFinder().atPosition([30, 20, 10]).findAll(b); // one cornerComposing filters
Every filter call narrows. Chain freely:
import { box, edgeFinder, getBounds } from 'brepjs/quick';
const b = box(30, 20, 10);
const topVerticals = edgeFinder()
.inDirection('Z')
.ofLength(10)
.when((e) => getBounds(e).zMax > 5) // edges that reach the upper half
.findAll(b);
console.log('Found', topVerticals.length, 'edges'); // 4 vertical edgesOrder doesn't matter for correctness (filters are additive) but for performance, put the most-selective filter first if you have many candidates.
With the fluent wrapper
The wrapper takes a finder callback, so you don't have to materialize the array yourself:
import { shape, box } from 'brepjs/quick';
const filleted = shape(box(30, 20, 10)).fillet((e) => e.inDirection('Z').ofLength(10), 1.5).val;
export default filleted;The callback receives an EdgeFinderFn (for .fillet, .chamfer) or FaceFinderFn (for .shell). You chain filters; the wrapper calls findAll internally.
Common patterns
"All edges except the inner hole"
When you want everything but the holes you just cut:
import { box, cylinder, cut, edgeFinder, fillet, getBounds, unwrap } from 'brepjs/quick';
const drilled = unwrap(cut(box(30, 20, 10), cylinder(5, 12, { at: [15, 10, -1] })));
// Vertical edges include the hole's 10mm seam edge, the same length as the box edges.
// Filter by position to exclude it: the box's vertical edges sit at x=0 and x=30.
const externalVerticals = edgeFinder()
.inDirection('Z')
.when((e) => getBounds(e).xMin < 1 || getBounds(e).xMin > 29)
.findAll(drilled);
const filleted = unwrap(fillet(drilled, externalVerticals, 1));
export default filleted;In practice, hole edges and exterior edges have different positions, lengths, or curve types. Find a filter that distinguishes them.
"Just the rim of this part"
The top circular edge of a cylindrical shell:
import { sketchCircle, edgeFinder, fillet, getBounds, unwrap } from 'brepjs/quick';
const cup = sketchCircle(20).extrude(40);
const rim = edgeFinder()
.ofCurveType('CIRCLE')
.when((e) => getBounds(e).zMin > 39)
.findAll(cup);
const rounded = unwrap(fillet(cup, rim, 2));
export default rounded;Two filters: circular curves only, in the upper millimetre. One match.
"The face that came from this sketch"
When you've fused parts together, finding "the face I just added" is harder. Heuristics:
import { box, sketchCircle, fuse, faceFinder, translate, unwrap } from 'brepjs/quick';
const base = box(40, 40, 5);
const boss = translate(sketchCircle(8).extrude(10), [20, 20, 5]);
const part = unwrap(fuse(base, boss));
// "The cylindrical face": easy
const bossSide = faceFinder().ofSurfaceType('CYLINDRE').findAll(part)[0];
console.log('Found boss cylindrical face');
void bossSide;
export default part;Surface type, area range, and direction together usually pin down a specific face. When they aren't enough, project face centres back to your input geometry to identify them.
What finders don't do
- They don't index by any kind of stable ID. Edge handles are bound to the shape they were found on; after an operation transforms the shape, the handles are stale.
- They don't traverse compounds across kernel boundaries; finders look at one shape at a time.
- They are not topology-aware in the sense of "edges connected to face X"; for that, use
edgesOfFace(face)frombrepjs/topology.
Edges have direction; finders sometimes don't care
inDirection('Z') matches edges parallel to Z, in either direction, and so does an explicit vector. If you need edges going specifically [0, 0, +1] (e.g. for face-orientation logic), check the tangent yourself in a .when() predicate.
Examples
These playground examples use edgeFinder to select the edges that a fillet or a chamfer changes.
Drilled bracket (5 lines)Box, drilled and filleted — the canonical loop.
DE-9 D-Sub Connector PairA DE-9 pair before it mates: a panel plug with two jackposts, and a solder-cup socket with jackscrews and wires, cut open at its upper contact row. The flange, the two shell sizes, the 2.77 by 2.84 mm contact grid and the 4-40 UNC thread are published figures. The jackscrews, the jackposts and their nuts have helical threads, and each jackscrew turns one turn for each pitch as the pair mates. The kernel measures the clearance between the mated shells. The insulators, the contacts, the hardware and the panel are a display model.
Vented Louvre Instrument CaseAn instrument case for a small linear power supply: a sliding cover with formed louvres, perforated side walls and a 40 mm fan behind a honeycomb grille. Inside are a toroidal transformer, two can capacitors and a regulator board. The fan frame and its 32 mm hole pitch, the M3 and M5 screw threads and heads and the open-area formula for round holes on 60 degree centres are published figures. Each screw has a helical thread in a mating nut, standoff or tapped hole. The kernel measures the open area of the side vents and prints it beside the formula. The case and the parts in it are a display model.
Pocket WatchAn open-face pocket watch with a hand-wound movement of the 16.5 ligne class: 36.6 mm, 17 jewels, 18,000 vibrations per hour. Each tooth count is from a published teardown, so the gear ratios are true, and the three hands show the time that the train gives them. The time parameter runs the watch. The screws have the miniature thread of ISO 1501, and in the exploded view each one turns out of its tapped hole. The bridges, the escapement shapes, the winding parts, the dial and the case are a display model.
Next steps
- Fillets & Chamfers: the operation finders are most often used for
- Measurement: measuring the entities you found
- The Topology Hierarchy: what each finder operates on