Query: Face

Face queries — read the topology and boundary geometry of a single BREP face. A FaceHandle is minted by walking from a BrepHandle; it is session-ephemeral and goes stale on undo/redo/re-topologize. Accessed via snaptrude.core.geom.query.face.

Traversals mint fresh child topology handles; position reads return Vec3Components. Holes are modelled per-loop: listHoles returns one seed half-edge per hole, and listHoleHalfEdges returns the full (flat) half-edge loop of one hole by index. No query mutates its inputs.

All methods resolve a face handle on the host, so an invalid, stale, or foreign handle rejects the call with HandleInvalidError (code HANDLE_INVALID).

Types

Vec3Components

Plain primitive record returned by position reads. Coordinates are in Snaptrude units — convert with snaptrude.core.units.convert(value, from, to).

Property	Type	Description
x	number	X component
y	number	Y component
z	number	Z component

Functions

getIndex(face)

Get the index of a face within its brep.

• Parameters:
  • face: FaceHandle — The face to query
• Returns: number — The index (-1 if unindexed)

---

getMaterialIndex(face)

Get the raw (unmapped) material index of a face.

• Parameters:
  • face: FaceHandle — The face to query
• Returns: number — The material index

---

getSurfaceKind(face)

Read what kind of surface a face lies on. This is the one read that tells a genuinely curved face from a faceted approximation of one: every face of a 200-triangle "dome" answers "plane", while a real dome has faces answering "sphere". Use it to confirm a curved solid actually came out curved.

Value	Surface
"plane"	Flat face
"cylinder"	Cylindrical face — constant radius about an axis
"cone"	Conical face — a tapered ring (a cone or frustum side)
"sphere"	Spherical face
"torus"	Toroidal face — the ring surface of a donut
"spline"	Free-form NURBS face

It is also how you select faces and edges on a curved solid: the flat base of a dome is its one "plane" face (the input for brepFromShell), and a rim is an edge whose two faces — read with edge.listFaces — are a cylinder and a plane (the input for brepFromFillet). Note that a closed curved surface is stored as several patches: a sphere answers "sphere" once per lune, not once for the whole ball.

Pure read: no geometry kernel is loaded.

• Parameters:
  • face: FaceHandle — The face to query
• Returns: "plane" | "cylinder" | "cone" | "sphere" | "torus" | "spline" | null — The surface kind, or null when the face carries no surface classification

// Census the faces of a mass: how many are actually curved?
const [mass] = await snaptrude.design.query.listMasses();
const brep = await snaptrude.design.query.geometry.getBrep(mass);
if (brep) {
  const faces = await snaptrude.core.geom.query.brep.listFaces(brep);
  const kinds = [];
  for (const face of faces) {
    kinds.push(await snaptrude.core.geom.query.face.getSurfaceKind(face));
  }
  console.log("spherical faces:", kinds.filter((k) => k === "sphere").length);
}

---

getHalfEdge(face)

Get a seed half-edge of a face's outer loop.

• Parameters:
  • face: FaceHandle — The face to query
• Returns: HalfEdgeHandle | null — The half-edge, or null for a degenerate face

const brep = await snaptrude.design.query.geometry.getBrep(component);
const faces = await snaptrude.core.geom.query.brep.listFaces(brep);
const seed = await snaptrude.core.geom.query.face.getHalfEdge(faces[0]);

---

listEdges(face)

List the edges of a face's outer loop.

• Parameters:
  • face: FaceHandle — The face to query
• Returns: EdgeHandle[] — The edges

---

listHalfEdges(face)

List the half-edges of a face's outer loop.

• Parameters:
  • face: FaceHandle — The face to query
• Returns: HalfEdgeHandle[] — The half-edges

---

listVertices(face)

List the vertices of a face's outer loop.

• Parameters:
  • face: FaceHandle — The face to query
• Returns: VertexHandle[] — The vertices

---

listHoles(face)

List a face's holes as one seed half-edge per hole loop.

• Parameters:
  • face: FaceHandle — The face to query
• Returns: HalfEdgeHandle[] — The hole seeds (one per hole)

---

getHoleCount(face)

Get the number of holes in a face.

• Parameters:
  • face: FaceHandle — The face to query
• Returns: number — The hole count

---

listHoleHalfEdges(face, holeIndex)

List the half-edge loop of one hole of a face (by hole index).

• Parameters:
  • face: FaceHandle — The face to query
  • holeIndex: number — Index of the hole (0..getHoleCount-1)
• Returns: HalfEdgeHandle[] — The hole's half-edges ([] if the index is out of range)

const face = snaptrude.core.geom.query.face;
const holeCount = await face.getHoleCount(myFace);
for (let i = 0; i < holeCount; i++) {
  const loop = await face.listHoleHalfEdges(myFace, i);
  console.log(`hole ${i} has ${loop.length} half-edges`);
}

---

hasHoles(face)

Test whether a face has any holes.

• Parameters:
  • face: FaceHandle — The face to query
• Returns: boolean — true if the face has at least one hole, otherwise false

---

getHoleContainingHalfEdge(face, halfEdge)

Get the seed half-edge of the hole loop containing a given half-edge.

• Parameters:
  • face: FaceHandle — The face to query
  • halfEdge: HalfEdgeHandle — The half-edge to locate
• Returns: HalfEdgeHandle | null — The hole seed, or null if the half-edge is not in any hole

---

listVertexPositions(face, brep)

List the positions of a face's outer-loop vertices (needs the parent brep for coordinates). Positions are in Snaptrude units.

• Parameters:
  • face: FaceHandle — The face to query
  • brep: BrepHandle — The parent brep (source of vertex coordinates)
• Returns: Vec3Components[] — The positions

const positions = await snaptrude.core.geom.query.face.listVertexPositions(myFace, brep);
for (const p of positions) {
  console.log(p.x, p.y, p.z);
}

---

getArea(face, brep)

Exact surface area of one face, in Snaptrude units squared — integrated off the face's own surface, not its facets, so a curved patch reads exactly rather than as its triangles. Needs the parent brep (owner last, as in listVertexPositions): a face handle cannot name its own solid. Convert with core.units.convert(value, from, to, 2) — area is degree 2.

• Parameters:
  • face: FaceHandle — The face to measure
  • brep: BrepHandle — The parent brep
• Returns: number — The area
• Throws: VALIDATION if face is not a face of brep; OPERATION_FAILED if the kernel could not measure the face

const faces = await snaptrude.core.geom.query.brep.listFaces(brep);
const areas = [];
for (const face of faces) {
  areas.push(await snaptrude.core.geom.query.face.getArea(face, brep));
}

---

getCentroid(face, brep)

Centre of area of one face, as a point in that brep's frame (Snaptrude units). On a solid whose every face reads "spline" this is the read that tells two patches apart — the top of a thickened patch from its bottom, one quarter of a closed surface from the next — so it is how you name a face of a recipe-less solid (a patch, a piece cut by a face) instead of trusting an index.

• Parameters:
  • face: FaceHandle — The face to measure
  • brep: BrepHandle — The parent brep (owner last)
• Returns: Vec3Components — The centroid
• Throws: VALIDATION if face is not a face of brep; OPERATION_FAILED if the kernel could not measure the face

const centre = await snaptrude.core.geom.query.face.getCentroid(face, brep);

---

listVertexPositionsWithCurves(face)

List the tessellated boundary points of a face's outer loop (arcs sampled, sense-corrected). Not cardinality-equal to listVertexPositions. Positions are in Snaptrude units.

• Parameters:
  • face: FaceHandle — The face to query
• Returns: Vec3Components[] — The boundary points

---

listAdjacentFaces(face)

List the faces adjacent to a face (sharing an edge). Boundary edges are skipped.

• Parameters:
  • face: FaceHandle — The face to query
• Returns: FaceHandle[] — The adjacent faces

Errors

Failed calls reject with a typed PluginError — see Error Handling. Conditions specific to this namespace:

Code	Thrown by	When	details
HANDLE_INVALID	all methods	The face handle is invalid, foreign, or stale (undo/redo/re-topologize invalidates it)	—

Beyond handle resolution the topology reads are total — a degenerate face (no seed half-edge) yields []/null rather than an error, and an unclassifiable face answers getSurfaceKind with null. The two measured reads, getArea and getCentroid, are the exception: they run on the kernel and refuse a face that is not a face of the brep they were passed with.