construction.Face
construction.Face(
kind,
key,
origin,
normal,
x_axis,
boundary,
*,
owner=None,
reference=None,
)One analytic planar face of a construction feature.
A face is a reference, not stored geometry: its origin and boundary are recomputed from the feature’s parameters every time the feature is built, so a sketch placed on it follows the parent and gradients flow through it.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| kind | str | cap (an extrusion or loft end), side (a swept polygon edge), or planar (a primitive’s flat face). |
required |
| key | str | Identity of the face within its owner — cap+, side3, +x. Stable across rebuilds, so the viewer can address it. |
required |
| origin | A point on the face, in world space. | required | |
| normal | Outward face normal in world space; normalized on construction. | required | |
| x_axis | The face’s in-plane “horizontal”; orthogonalized against the normal so the frame is orthonormal whatever the caller passes. | required | |
| boundary | The face’s boundary loop in world space, shape (M, 3). |
required | |
| owner | The feature or primitive that declared the face. | None |
|
| reference | tuple[str, tuple] | None | (method, args) naming the accessor that returns this face — ("cap", ("+",)) — which is what the viewer writes back into the user’s source. |
None |
Attributes
| Name | Description |
|---|---|
| y_axis | The in-plane axis completing a right-handed frame with the normal. |
Methods
| Name | Description |
|---|---|
| center | The centroid of the face’s boundary loop, in world space. |
| contains | Whether a world point lies on this face, within tol. |
| describe | Serialize the face for the viewer. |
| diagonal | Diagonal of the face’s bounding box — the scale a tolerance is read against. |
| frame | Return the orthonormal (x, y, normal) frame of the face. |
| hole | A cylindrical tool sunk into this face — subtract it to cut a hole. |
| plane | This face as a sketch plane, optionally pushed along its normal. |
| A prismatic tool sunk into this face — subtract it to cut a pocket. | |
| point | A world point at face-local coordinates at, measured from the origin. |
| polygon | The boundary loop in face coordinates, shape (M, 2). |
| to_local | Project world points (..., 3) onto the face’s (..., 2) axes. |
| tolerance | Default hit tolerance for :meth:contains, scaled to the face. |
center
construction.Face.center()The centroid of the face’s boundary loop, in world space.
The natural anchor for a feature placed “on the middle of this face” — a boss, a bore, a bolt circle’s axis — and, being an average of the boundary, an expression in the parent’s parameters like everything else on the face.
Returns
| Name | Type | Description |
|---|---|---|
| Array | The centroid, shape (3,). |
contains
construction.Face.contains(point, tol=None)Whether a world point lies on this face, within tol.
Two tests, both inclusive of the tolerance: the point must sit within tol of the face’s plane, and its in-plane projection must lie inside the boundary polygon (again allowing tol of slack, so a hit exactly on a shared edge belongs to both faces rather than neither).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| point | World point(s), shape (..., 3). |
required | |
| tol | float | None | Distance tolerance; defaults to :meth:tolerance. |
None |
Returns
| Name | Type | Description |
|---|---|---|
| Array | Boolean array shaped like point without its last axis. |
describe
construction.Face.describe()Serialize the face for the viewer.
Returns
| Name | Type | Description |
|---|---|---|
| FaceDescription | A JSON-ready dict carrying the face’s identity, its plane frame, the world-space boundary polygon the viewer highlights, the tolerance a hit test should use, and the accessor call that reproduces the face in source. |
diagonal
construction.Face.diagonal()Diagonal of the face’s bounding box — the scale a tolerance is read against.
frame
construction.Face.frame()Return the orthonormal (x, y, normal) frame of the face.
hole
construction.Face.hole(
radius,
depth,
at=(0.0, 0.0),
*,
through=0.0,
material=None,
)A cylindrical tool sunk into this face — subtract it to cut a hole.
Returns the tool rather than a modified solid, because in an implicit modeller the cut is the boolean: keeping them separate is what lets one tool be patterned, mirrored, or subtracted from several bodies at once, and what keeps the hole visible in the feature tree.
The tool is a true :class:~cadjoint.sdf.primitives.cylinder.Cylinder aligned with the face normal, not a polygonal approximation, so the bore stays round at every render scale and its radius stays a live design parameter.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| radius | Bore radius; may be a Scalar parameter. |
required | |
| depth | How far the tool reaches below the face, along -normal. May be a Scalar. |
required | |
| at | Where the axis meets the face, in face-local (x, y). |
(0.0, 0.0) |
|
| through | float | Extra length added above the face. Zero leaves the tool exactly flush, which is what a blind hole wants; a small positive value keeps a through-hole’s mouth off the surface it is cutting, where a perfectly coincident pair of surfaces would otherwise leave the mesher to break the tie. | 0.0 |
| material | Optional render material for the tool. | None |
Returns
| Name | Type | Description |
|---|---|---|
| The tool as an SDF, placed in world space. |
Example
bore = flange.cap("+").hole(bore_radius, depth=0.4, through=0.02)
housing = Difference(flange, bore)plane
construction.Face.plane(x_axis=None, flip=False, offset=0.0)This face as a sketch plane, optionally pushed along its normal.
Sugar for :meth:~cadjoint.construction.sketch.SketchPlane.on — and, with an offset, for :meth:~cadjoint.construction.sketch.SketchPlane.offset — so a face reference reads as one phrase where it is used.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| x_axis | Override the sketch’s in-plane horizontal. | None |
|
| flip | bool | Face the plane the other way, keeping the same origin. | False |
| offset | Distance to push along the (possibly flipped) normal. May be a Scalar parameter. |
0.0 |
Returns
| Name | Type | Description |
|---|---|---|
| The | class:~cadjoint.construction.sketch.SketchPlane. |
construction.Face.pocket(
vertices,
depth,
at=(0.0, 0.0),
*,
through=0.0,
material=None,
)A prismatic tool sunk into this face — subtract it to cut a pocket.
The profile is read in the face’s own frame, so a pocket is drawn in the same coordinates the face’s other features use.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| vertices | The pocket outline as face-local (x, y) points — a list, or a :class:PolygonProfile’s vertices. |
required | |
| depth | How far the tool reaches below the face, along -normal. |
required | |
| at | Offset applied to the whole outline, in face-local (x, y). |
(0.0, 0.0) |
|
| through | float | Extra length added above the face; see :meth:hole. |
0.0 |
| material | Optional render material for the tool. | None |
Returns
| Name | Type | Description |
|---|---|---|
| The tool as an SDF, placed in world space. |
point
construction.Face.point(at=(0.0, 0.0))A world point at face-local coordinates at, measured from the origin.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| at | (x, y) in the face’s own frame — x along :attr:x_axis, y along :attr:y_axis. |
(0.0, 0.0) |
Returns
| Name | Type | Description |
|---|---|---|
| Array | The world point, shape (3,). |
polygon
construction.Face.polygon()The boundary loop in face coordinates, shape (M, 2).
to_local
construction.Face.to_local(points)Project world points (..., 3) onto the face’s (..., 2) axes.
tolerance
construction.Face.tolerance()Default hit tolerance for :meth:contains, scaled to the face.