From 0b86d4f81ffb4ec36eb2807d81411543584c0886 Mon Sep 17 00:00:00 2001 From: Pranjal Bhatia <233476158+pranjalbhatia710@users.noreply.github.com> Date: Sun, 7 Jun 2026 10:02:49 +0400 Subject: [PATCH] docs: explain Workplane tag and end usage --- doc/workplane.rst | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) 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