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

---

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);
}

---

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 these reads are total — a degenerate face (no seed half-edge) yields []/null rather than an error.