diff --git a/doc/workplane.rst b/doc/workplane.rst index ba52064da..7286f4a50 100644 --- a/doc/workplane.rst +++ b/doc/workplane.rst @@ -81,6 +81,41 @@ backwards in the stack to get the face as well:: You can browse stack access methods here: :ref:`stackMethods`. +.. _tagging-workplanes: + +Tagging Workplanes +--------------------------- + +Longer parametric models often need to leave a selection, add more geometry, and then return to +that earlier selection. Two small stack helpers are useful for this: + +* :meth:`~cadquery.Workplane.end` returns the parent Workplane, which is usually the object you + had before the most recent selector or construction call. +* :meth:`~cadquery.Workplane.tag` names a Workplane so later selector calls can start from that + point in the chain by using their ``tag`` keyword argument. + +For example, the two ``tag`` calls below select faces only long enough to name them. The following +``end`` calls move back to the box Workplane so the next operation still starts from the whole part:: + + import cadquery as cq + + bracket = cq.Workplane("XY").box(4, 2, 0.5) + bracket.faces(">X").tag("right_face").end() + bracket.faces("Z").workplane().hole(0.25) + +The tags remain available from the shared modelling context. A later selector can pass the tag name +to select relative to the tagged Workplane instead of relative to the current stack:: + + right_edges = result.edges("|Z", tag="right_face") + left_edges = result.edges("|Z", tag="left_face") + +This keeps feature references close to the geometry they describe, instead of depending on how many +``end`` calls are needed to walk back through the chain. It is especially helpful in assemblies, +where tagged faces and edges are commonly used as stable mating references. + + .. _chaining: Chaining