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 1/3] 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 From f70dee753a291b0acf3ee175830781eb27a09364 Mon Sep 17 00:00:00 2001 From: Pranjal Bhatia <233476158+pranjalbhatia710@users.noreply.github.com> Date: Wed, 15 Jul 2026 01:18:14 +0400 Subject: [PATCH 2/3] docs: add tag follow-up examples --- doc/workplane.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/doc/workplane.rst b/doc/workplane.rst index 7286f4a50..f2c903ad3 100644 --- a/doc/workplane.rst +++ b/doc/workplane.rst @@ -111,6 +111,23 @@ to select relative to the tagged Workplane instead of relative to the current st right_edges = result.edges("|Z", tag="right_face") left_edges = result.edges("|Z", tag="left_face") +When you do need to walk back through the chain, :meth:`~cadquery.Workplane.end` also accepts a +count. For example, ``.end(3)`` returns the third parent Workplane, which is useful after a short +run of selectors has narrowed the stack more than once:: + + box = cq.Workplane("XY").box(4, 2, 0.5) + top_face = box.faces(">Z").edges("|X").vertices().end(3) + +You can also create a new Workplane from a tag instead of only selecting from it. This is useful +when the tagged Workplane's plane and objects are the right starting point for another feature:: + + result = ( + bracket + .workplaneFromTagged("right_face") + .center(0, 0.35) + .hole(0.2) + ) + 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. From d8e7cef588d45bab145dcecbddb9e8f57876db0d Mon Sep 17 00:00:00 2001 From: Pranjal Bhatia <233476158+pranjalbhatia710@users.noreply.github.com> Date: Wed, 15 Jul 2026 07:21:39 +0400 Subject: [PATCH 3/3] docs: place tagging after chaining overview --- doc/workplane.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/doc/workplane.rst b/doc/workplane.rst index f2c903ad3..e1e025827 100644 --- a/doc/workplane.rst +++ b/doc/workplane.rst @@ -81,6 +81,21 @@ backwards in the stack to get the face as well:: You can browse stack access methods here: :ref:`stackMethods`. +.. _chaining: + +Chaining +--------------------------- + +All Workplane methods return another Workplane object, so that you can chain the methods together +fluently. Use the core Workplane methods to get at the objects that were created. + +Each time a new Workplane object is produced during these chained calls, it has a +:attr:`~cadquery.Workplane.parent` attribute that points to the Workplane object that created it. +Several CadQuery methods search this parent chain, for example when searching for the context solid. +You can also give a Workplane object a tag, and further down your chain of calls you can refer back +to this particular object using its tag. + + .. _tagging-workplanes: Tagging Workplanes @@ -133,21 +148,6 @@ This keeps feature references close to the geometry they describe, instead of de where tagged faces and edges are commonly used as stable mating references. -.. _chaining: - -Chaining ---------------------------- - -All Workplane methods return another Workplane object, so that you can chain the methods together -fluently. Use the core Workplane methods to get at the objects that were created. - -Each time a new Workplane object is produced during these chained calls, it has a -:attr:`~cadquery.Workplane.parent` attribute that points to the Workplane object that created it. -Several CadQuery methods search this parent chain, for example when searching for the context solid. -You can also give a Workplane object a tag, and further down your chain of calls you can refer back -to this particular object using its tag. - - The Context Solid ---------------------------