FaceFilter
Creates a new face filter builder for selecting faces by geometric properties.
import { face } from 'fluidcad/filters';
Methods
.onPlane()
.onPlane(plane: SceneObject | PlaneLike, offset?: number): this
Selects faces that lie on the given plane. Besides a standard plane or a
plane feature, any scene object whose first shape is a face works as the
reference — a bucket accessor like e.endFaces(), or a select(). The
face is only read to derive its plane (no plane feature is created, and
the referenced geometry is not consumed), so the reference stays valid
even when a later feature reshaped or consumed the face.
| Parameter | Type | Description |
|---|---|---|
plane | SceneObject | PlaneLike | The reference plane, plane feature, or face selection. |
offset | number | Optional distance to offset a standard plane before matching. (optional) |
.notOnPlane()
.notOnPlane(plane: SceneObject | PlaneLike, offset?: number): this
Excludes faces that lie on the given plane. Accepts the same references
as onPlane, including a face selection to read the plane from.
| Parameter | Type | Description |
|---|---|---|
plane | SceneObject | PlaneLike | The reference plane, plane feature, or face selection. |
offset | number | Optional distance to offset a standard plane before matching. (optional) |
.circle()
.circle(diameter?: number): this
Selects circular (flat, disc-shaped) faces, optionally matching a specific diameter.
| Parameter | Type | Description |
|---|---|---|
diameter | number | Optional diameter to match. (optional) |
.notCircle()
.notCircle(diameter?: number): this
Excludes circular (flat, disc-shaped) faces, optionally matching a specific diameter.
| Parameter | Type | Description |
|---|---|---|
diameter | number | Optional diameter to exclude. (optional) |
.cylinder()
.cylinder(diameter?: number): this
Selects full cylindrical faces — ones that wrap all the way around their
axis and so carry a circular rim: a hole's bore, a boss's wall.
A partial cylinder (a fillet face, a bore cut open by a slot) is a
cylinderCurve.
| Parameter | Type | Description |
|---|---|---|
diameter | number | Optional diameter to match. (optional) |
.notCylinder()
.notCylinder(diameter?: number): this
Excludes full cylindrical faces (see cylinder), optionally
matching a specific diameter.
| Parameter | Type | Description |
|---|---|---|
diameter | number | Optional diameter to exclude. (optional) |
.cylinderCurve()
.cylinderCurve(diameter?: number): this
Selects partial cylindrical faces — ones that do not wrap all the way
around their axis: a fillet along an edge, a rounded corner of a pad, a
bore cut open by a slot. A full bore is a cylinder.
| Parameter | Type | Description |
|---|---|---|
diameter | number | Optional diameter to match (a fillet of radius r has diameter 2r). (optional) |
.notCylinderCurve()
.notCylinderCurve(diameter?: number): this
Excludes partial cylindrical faces (see cylinderCurve),
optionally matching a specific diameter.
| Parameter | Type | Description |
|---|---|---|
diameter | number | Optional diameter to exclude. (optional) |
.parallelTo()
.parallelTo(plane: PlaneLike): this
Selects faces whose normal is parallel to the given plane.
| Parameter | Type | Description |
|---|---|---|
plane | PlaneLike | The reference plane. |
.notParallelTo()
.notParallelTo(plane: PlaneLike): this
Excludes faces whose normal is parallel to the given plane.
| Parameter | Type | Description |
|---|---|---|
plane | PlaneLike | The reference plane. |
.torus()
.torus(majorRadius?: number, minorRadius?: number): this
Selects toroidal faces, optionally matching major and/or minor radius.
| Parameter | Type | Description |
|---|---|---|
majorRadius | number | Optional radius from the torus axis to the tube center. (optional) |
minorRadius | number | Optional radius of the tube itself. (optional) |
.notTorus()
.notTorus(majorRadius?: number, minorRadius?: number): this
Excludes toroidal faces, optionally matching major and/or minor radius.
| Parameter | Type | Description |
|---|---|---|
majorRadius | number | Optional radius from the torus axis to the tube center. (optional) |
minorRadius | number | Optional radius of the tube itself. (optional) |
.planar()
.planar(): this
Selects planar (flat) faces.
.notPlanar()
.notPlanar(): this
Excludes planar (flat) faces.
.cone()
.cone(): this
Selects conical faces.
.notCone()
.notCone(): this
Excludes conical faces.
.intersectsWith()
.intersectsWith(plane: PlaneLike): this
Selects faces that intersect with the given plane.
| Parameter | Type | Description |
|---|---|---|
plane | PlaneLike | The reference plane to test intersection against. |
.notIntersectsWith()
.notIntersectsWith(plane: PlaneLike): this
Excludes faces that intersect with the given plane.
| Parameter | Type | Description |
|---|---|---|
plane | PlaneLike | The reference plane to test intersection against. |
.hasEdge()
.hasEdge(...args: any[][]): this
| Parameter | Type | Description |
|---|---|---|
...args | any[] | (optional) |
.notHasEdge()
.notHasEdge(...args: any[][]): this
| Parameter | Type | Description |
|---|---|---|
...args | any[] | (optional) |
.edgeCount()
.edgeCount(count: number): this
Selects faces with exactly the given number of edges. Only model edges count: a cylinder's seam and the degenerate apex of a cone or pole of a sphere are neither drawn nor counted, so a cylinder's side face has 2.
| Parameter | Type | Description |
|---|---|---|
count | number | The exact number of edges to match. |
.notEdgeCount()
.notEdgeCount(count: number): this
Excludes faces with the given number of edges.
| Parameter | Type | Description |
|---|---|---|
count | number | The number of edges to exclude. |
.above()
.above(plane: SceneObject | PlaneLike, offsetOrOptions?: number | { offset?: number; partial?: boolean; }): this
Selects faces that are entirely above the given plane (in the direction of its normal). Besides a
standard plane or a plane feature, any scene object whose first shape is
a face works as the reference — a bucket accessor like base.endFaces()
— so the half-space follows the referenced feature through edits. The
offset runs along the resolved plane's normal.
| Parameter | Type | Description |
|---|---|---|
plane | SceneObject | PlaneLike | The reference plane, plane feature, or face selection. |
offsetOrOptions | number | { offset?: number; partial?: boolean; } | Offset distance, or an options object with offset and partial. (optional) |
.below()
.below(plane: SceneObject | PlaneLike, offsetOrOptions?: number | { offset?: number; partial?: boolean; }): this
Selects faces that are entirely below the given plane (opposite to its normal direction). Besides a
standard plane or a plane feature, any scene object whose first shape is
a face works as the reference — a bucket accessor like base.endFaces()
— so the half-space follows the referenced feature through edits. The
offset runs along the resolved plane's normal.
| Parameter | Type | Description |
|---|---|---|
plane | SceneObject | PlaneLike | The reference plane, plane feature, or face selection. |
offsetOrOptions | number | { offset?: number; partial?: boolean; } | Offset distance, or an options object with offset and partial. (optional) |
.from()
.from(...sceneObjects: SceneObject[][]): this
Restricts the selection to faces originating from the given scene objects. Recursive: passing a container picks up faces from its descendants.
| Parameter | Type | Description |
|---|---|---|
...sceneObjects | SceneObject[] | Scene objects whose faces (and faces of their sub-shapes) are matched against. (optional) |
.farthest()
.farthest(direction: DirectionLike): this
Keeps the layer of faces farthest along a direction — every edge whose
center of mass lies at the maximum (within tolerance) along it. A box's
farthest('z') is its top face; chain order is evaluation
order, so face().planar().farthest('z') ranks only the planar faces.
| Parameter | Type | Description |
|---|---|---|
direction | DirectionLike | 'x', 'y', 'z', '-x', '-y', '-z', a vector, or an axis. |
.notFarthest()
.notFarthest(direction: DirectionLike): this
Excludes the layer of faces farthest along a direction.
| Parameter | Type | Description |
|---|---|---|
direction | DirectionLike | 'x', 'y', 'z', '-x', '-y', '-z', a vector, or an axis. |
.nearest()
.nearest(direction: DirectionLike): this
Keeps the layer of faces nearest along a direction — the minimum of the
center of mass along it (nearest('z') is the same as farthest('-z')).
| Parameter | Type | Description |
|---|---|---|
direction | DirectionLike | 'x', 'y', 'z', '-x', '-y', '-z', a vector, or an axis. |
.notNearest()
.notNearest(direction: DirectionLike): this
Excludes the layer of faces nearest along a direction.
| Parameter | Type | Description |
|---|---|---|
direction | DirectionLike | 'x', 'y', 'z', '-x', '-y', '-z', a vector, or an axis. |
.nth()
.nth(direction: DirectionLike, index: number): this
Keeps the k-th layer of faces along a direction, counting layers of
equal center position from the near end (0-based); a negative index
counts from the far end, so nth('z', -1) is farthest('z').
| Parameter | Type | Description |
|---|---|---|
direction | DirectionLike | 'x', 'y', 'z', '-x', '-y', '-z', a vector, or an axis. |
index | number | Layer index; out-of-range indices match nothing. |
.largest()
.largest(measure?: SizeMeasure): this
Keeps the largest faces — by area unless a measure is given — including every face that ties with the largest.
| Parameter | Type | Description |
|---|---|---|
measure | SizeMeasure | 'area' (default) or 'radius' for circular faces. (optional) |
.notLargest()
.notLargest(measure?: SizeMeasure): this
Excludes the largest faces (and their ties).
| Parameter | Type | Description |
|---|---|---|
measure | SizeMeasure | 'area' (default) or 'radius'. (optional) |
.smallest()
.smallest(measure?: SizeMeasure): this
Keeps the smallest faces — by area unless a measure is given — including every face that ties with the smallest.
| Parameter | Type | Description |
|---|---|---|
measure | SizeMeasure | 'area' (default) or 'radius' for circular faces. (optional) |
.notSmallest()
.notSmallest(measure?: SizeMeasure): this
Excludes the smallest faces (and their ties).
| Parameter | Type | Description |
|---|---|---|
measure | SizeMeasure | 'area' (default) or 'radius'. (optional) |